Templates API

Templates are the mechanism through which WPfaker stores and retrieves reusable generation configurations. A template captures every setting that controls how content is generated for a specific post type: which fields to populate, how to generate values for each field, how taxonomy terms should be assigned, which image provider to use, and what variation profile to apply. Once a template is saved, it can be loaded in a single step on subsequent generation runs, ensuring consistency and saving you from reconfiguring the same options repeatedly.

The Templates API provides full CRUD operations on local templates, along with endpoints for duplicating templates, setting defaults, exporting and importing templates as portable JSON, and querying the fields available for a post type. This makes it possible to build automated workflows that create templates programmatically, share configurations between environments, and integrate template management into deployment scripts.

TIP

For general information about authentication, error codes, and response format, see the REST API Overview. To learn about the template system from a user perspective, see the Template System feature guide.

List Templates

Retrieve all saved templates, optionally filtered by post type. The response includes basic metadata for each template but does not include the full field configuration. Use the Get Single Template endpoint to retrieve the complete configuration for a specific template.

Endpoint

GET /wp-json/wpfaker/v1/templates

Query Parameters

Parameter	Type	Required	Default	Description
`post_type`	string	No	—	Filter templates to those targeting a specific post type
`is_system`	boolean	No	—	Filter by system template status. When `true`, returns only system templates; when `false`, returns only user templates. Omit to return all templates.

Example: List All Templates

bash

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

Example: Filter by Post Type

bash

curl "https://yoursite.com/wp-json/wpfaker/v1/templates?post_type=product" \
  -H "X-WP-Nonce: your-nonce"

Response

json

{
  "success": true,
  "templates": [
    {
      "id": 1,
      "name": "Blog Posts - Full Content",
      "description": "Complete blog posts with images and taxonomies",
      "post_type": "post",
      "is_default": true,
      "is_system": false,
      "created_at": "2024-01-15 10:30:00",
      "updated_at": "2024-01-16 14:20:00"
    },
    {
      "id": 2,
      "name": "Properties - Minimal",
      "description": "Basic property listings",
      "post_type": "property",
      "is_default": false,
      "is_system": false,
      "created_at": "2024-01-14 09:00:00",
      "updated_at": "2024-01-14 09:00:00"
    }
  ],
  "total": 2,
  "stale": [],
  "adapter_info": {
    "post": {
      "fields": ["subtitle", "hero_image"],
      "taxonomies": ["category", "post_tag"],
      "adapters": ["ACF Pro"]
    }
  }
}

Get Single Template

Retrieve a specific template by ID, including its complete field configuration, taxonomy configuration, and all metadata. This is the endpoint to use when you need to inspect or modify a template's settings programmatically.

Endpoint

GET /wp-json/wpfaker/v1/templates/{id}

Example Request

bash

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

Response

json

{
  "success": true,
  "template": {
    "id": 1,
    "name": "Blog Posts - Full Content",
    "description": "Complete blog posts with images and taxonomies",
    "post_type": "post",
    "is_default": true,
    "is_system": false,
    "field_config": {
      "core_fields": {
        "post_title": {
          "mode": "create",
          "create": {
            "method": "words",
            "word_count_min": 3,
            "word_count_max": 10
          }
        },
        "post_content": {
          "mode": "create",
          "create": {
            "method": "paragraphs",
            "paragraph_count_min": 3,
            "paragraph_count_max": 6
          }
        }
      },
      "custom_fields": {
        "subtitle": {
          "mode": "create",
          "field_type": "text",
          "create": {
            "method": "sentence"
          }
        }
      }
    },
    "taxonomy_config": {
      "category": {
        "mode": "choose",
        "choose": {
          "term_ids": [5, 10, 15],
          "count_min": 1,
          "count_max": 3
        }
      }
    },
    "linked_parents": [],
    "created_at": "2024-01-15 10:30:00",
    "updated_at": "2024-01-16 14:20:00"
  }
}

Create Template

Create a new template with the specified name, post type, and optional configuration. The template is immediately available for use in generation requests via the template_id parameter on the Generate Posts endpoint.

Endpoint

POST /wp-json/wpfaker/v1/templates

Parameters

Parameter	Type	Required	Description
`name`	string	Yes	Display name for the template
`description`	string	No	A brief description explaining the template's purpose
`post_type`	string	Yes	The post type this template targets. Cannot be changed after creation.
`is_default`	boolean	No	Set this template as the default for its post type. When a post type has a default template, it is automatically selected on the generation screen.
`field_config`	object	No	Field configuration object containing `core_fields` and `custom_fields` settings
`taxonomy_config`	object	No	Taxonomy configuration object specifying how terms are assigned

INFO

Setting is_default to true automatically unsets the default flag on any other template targeting the same post type. Each post type can have at most one default template.

Example Request

bash

curl -X POST "https://yoursite.com/wp-json/wpfaker/v1/templates" \
  -H "X-WP-Nonce: your-nonce" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Products - E-commerce",
    "description": "Product listings with prices and images",
    "post_type": "product",
    "is_default": true,
    "field_config": {
      "core_fields": {
        "post_title": {
          "mode": "create",
          "create": {"method": "words", "word_count_min": 2, "word_count_max": 5}
        }
      },
      "custom_fields": {
        "price": {
          "mode": "create",
          "field_type": "number",
          "create": {"min": 10, "max": 500}
        }
      }
    }
  }'

Response

json

{
  "success": true,
  "message": "Template created successfully",
  "template": {
    "id": 3,
    "name": "Products - E-commerce",
    "description": "Product listings with prices and images",
    "post_type": "product",
    "is_default": true,
    "is_system": false,
    "field_config": { "...": "..." },
    "taxonomy_config": {},
    "created_at": "2024-01-17 09:00:00",
    "updated_at": "2024-01-17 09:00:00"
  }
}

Update Template

Update an existing template. You can modify any property except post_type, which is immutable after creation. Only the fields you include in the request body are updated — omitted fields retain their current values.

Endpoint

PUT /wp-json/wpfaker/v1/templates/{id}

Parameters

The same parameters as Create Template, except post_type is not accepted.

Example Request

bash

curl -X PUT "https://yoursite.com/wp-json/wpfaker/v1/templates/3" \
  -H "X-WP-Nonce: your-nonce" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Products - Premium",
    "description": "Updated product template with expanded field coverage",
    "field_config": {
      "core_fields": {
        "post_title": {
          "mode": "create",
          "create": {"method": "words", "word_count_min": 3, "word_count_max": 8}
        },
        "post_content": {
          "mode": "create",
          "create": {"method": "paragraphs", "paragraph_count_min": 2, "paragraph_count_max": 5}
        }
      },
      "custom_fields": {
        "price": {
          "mode": "create",
          "field_type": "number",
          "create": {"min": 50, "max": 2000, "decimal_places": 2}
        },
        "sku": {
          "mode": "create",
          "field_type": "text",
          "create": {"method": "words", "word_count_min": 1, "word_count_max": 1}
        }
      }
    }
  }'

Response

json

{
  "success": true,
  "message": "Template updated successfully",
  "template": {
    "id": 3,
    "name": "Products - Premium",
    "description": "Updated product template with expanded field coverage",
    "post_type": "product",
    "is_default": true,
    "is_system": false,
    "field_config": { "...": "..." },
    "taxonomy_config": {},
    "created_at": "2024-01-17 09:00:00",
    "updated_at": "2024-01-18 11:30:00"
  }
}

Delete Template

Permanently delete a template by ID. This action cannot be undone. If the deleted template was the default for its post type, you can pass new_default_id to promote another template as the new default in the same request.

Endpoint

DELETE /wp-json/wpfaker/v1/templates/{id}

Parameters

Parameter	Type	Required	Description
`new_default_id`	integer	No	ID of another template to set as the new default for this post type. Useful when deleting the current default template.

Example Request

bash

curl -X DELETE "https://yoursite.com/wp-json/wpfaker/v1/templates/3?new_default_id=1" \
  -H "X-WP-Nonce: your-nonce"

Response

json

{
  "success": true,
  "message": "Template deleted successfully",
  "variants_deleted": 0
}

The variants_deleted field indicates how many child variants were also deleted along with the parent template.

Set Default Template

Mark a template as the default for its post type. The default template is automatically pre-selected when you open the generation screen for that post type, both in the admin UI and when no template_id is specified in an API generation request.

Endpoint

POST /wp-json/wpfaker/v1/templates/{id}/default

Example Request

bash

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

Response

json

{
  "success": true,
  "message": "Template set as default",
  "template": {
    "id": 1,
    "name": "Blog Posts - Full Content",
    "is_default": true,
    "...": "..."
  }
}

INFO

Each post type can have at most one default template. Setting a new default automatically removes the default flag from the previous default template for the same post type.

Duplicate Template

Create an exact copy of an existing template. The duplicate receives a name with "(Copy)" appended and is not set as default, regardless of the original's default status. This is useful for creating variants of a working template without modifying the original.

Endpoint

POST /wp-json/wpfaker/v1/templates/{id}/duplicate

Example Request

bash

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

Response

json

{
  "success": true,
  "message": "Template duplicated successfully",
  "template": {
    "id": 4,
    "name": "Blog Posts - Full Content (Copy)",
    "description": "Complete blog posts with images and taxonomies",
    "post_type": "post",
    "is_default": false,
    "is_system": false,
    "field_config": { "...": "..." },
    "taxonomy_config": { "...": "..." },
    "created_at": "2024-01-18 15:00:00",
    "updated_at": "2024-01-18 15:00:00"
  }
}

Export Templates

Export one or more templates as portable JSON that can be saved to a file and imported into another WordPress installation. You can export specific templates by ID or all templates for a post type. The exported JSON includes template names, descriptions, post types, field configurations, taxonomy configurations, and export metadata. It does not include database IDs or installation-specific data.

Endpoint

GET /wp-json/wpfaker/v1/templates/export

Query Parameters

Parameter	Type	Required	Description
`ids`	array	No	Array of template IDs to export. Omit to export by post type instead.
`post_type`	string	No	Export all templates targeting this post type. Ignored when `ids` is provided.

Example: Export Specific Templates

bash

curl "https://yoursite.com/wp-json/wpfaker/v1/templates/export?ids[]=1&ids[]=3" \
  -H "X-WP-Nonce: your-nonce"

Example: Export by Post Type

bash

curl "https://yoursite.com/wp-json/wpfaker/v1/templates/export?post_type=product" \
  -H "X-WP-Nonce: your-nonce"

Response

json

{
  "success": true,
  "templates": [
    {
      "name": "Blog Posts - Full Content",
      "description": "Complete blog posts with images and taxonomies",
      "post_type": "post",
      "field_config": {
        "core_fields": { "...": "..." },
        "custom_fields": { "...": "..." }
      },
      "taxonomy_config": { "...": "..." }
    }
  ],
  "count": 1,
  "version": "1.0",
  "exported": "2025-03-15 12:00:00"
}

TIP

You can pipe the curl output directly to a file for backup purposes: curl ... > template-backup.json. To import the templates on another site, pass the saved JSON to the Import Template endpoint.

Import Template

Import one or more templates from a previously exported JSON payload. The import process creates new local templates with new database IDs. Pass the templates array from the export response directly.

Endpoint

POST /wp-json/wpfaker/v1/templates/import

Parameters

Parameter	Type	Required	Description
`templates`	array	Yes	Array of template objects from the export endpoint's `templates` array

Example Request

bash

curl -X POST "https://yoursite.com/wp-json/wpfaker/v1/templates/import" \
  -H "X-WP-Nonce: your-nonce" \
  -H "Content-Type: application/json" \
  -d '{
    "templates": [
      {
        "name": "Blog Posts - Full Content",
        "post_type": "post",
        "field_config": {
          "core_fields": {
            "post_title": {
              "mode": "create",
              "create": {"method": "words", "word_count_min": 3, "word_count_max": 10}
            }
          }
        },
        "taxonomy_config": {}
      }
    ]
  }'

Response

json

{
  "success": true,
  "message": "Imported 1 templates. 0 failed.",
  "results": [
    {
      "success": true,
      "name": "Blog Posts - Full Content",
      "id": 5
    }
  ]
}

Get Fields for Post Type

Retrieve all fields available for a given post type, organized into core fields, custom fields (from active field plugin adapters), and associated taxonomies. This endpoint is primarily used by the template editor UI to populate the field list, but it is equally useful when building templates programmatically — it tells you exactly which fields exist and what types they are, so you can construct valid field_config objects.

Endpoint

GET /wp-json/wpfaker/v1/templates/fields/{post_type}

Example Request

bash

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

Response

json

{
  "success": true,
  "post_type": "product",
  "core_fields": {
    "post_title": {
      "name": "post_title",
      "label": "Title",
      "type": "post_title",
      "category": "text",
      "required": true,
      "modes": ["none", "create", "choose"],
      "default": { "...": "..." }
    },
    "post_content": {
      "name": "post_content",
      "label": "Content",
      "type": "post_content",
      "category": "text",
      "required": false,
      "modes": ["none", "create", "choose"],
      "default": { "...": "..." }
    }
  },
  "custom_fields": {
    "acf-pro": {
      "group_title": "ACF Pro",
      "fields": [
        {
          "key": "field_abc123",
          "name": "price",
          "label": "Price",
          "type": "number",
          "category": "number",
          "required": true,
          "modes": ["none", "create", "choose"],
          "default": { "...": "..." }
        },
        {
          "key": "field_def456",
          "name": "sku",
          "label": "SKU",
          "type": "text",
          "category": "text",
          "required": false,
          "modes": ["none", "create", "choose"],
          "default": { "...": "..." }
        }
      ]
    }
  }
}

INFO

The fields returned by this endpoint depend on which field plugin adapters are active. If you install ACF and register field groups for a post type, those fields will appear in the response. If you later deactivate ACF, those fields will no longer be listed. See the Information API for details on checking which adapters are active.

Get Taxonomies for Post Type

Retrieve all taxonomies registered for a given post type. This endpoint powers the taxonomy configuration section of the template editor, but it is equally useful when building templates programmatically — it tells you which taxonomies are available for term assignment.

Endpoint

GET /wp-json/wpfaker/v1/templates/taxonomies/{post_type}

Example Request

bash

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

Get Taxonomy Terms

Retrieve terms for a specific taxonomy with optional search and parent filtering. This endpoint supports the term selector in the template editor where users pick specific terms for the choose taxonomy mode. Pagination is controlled through the per_page parameter.

Endpoint

GET /wp-json/wpfaker/v1/taxonomies/{taxonomy}/terms

Query Parameters

Parameter	Type	Required	Default	Description
`taxonomy`	string	Yes	—	The taxonomy slug to retrieve terms from
`search`	string	No	—	Filter terms by name (partial match)
`parent`	integer	No	—	Filter to direct children of this term ID. Use `0` for top-level terms.
`per_page`	integer	No	100	Maximum number of terms to return

Example: Search Terms

bash

curl "https://yoursite.com/wp-json/wpfaker/v1/taxonomies/product_cat/terms?search=electronics&per_page=50" \
  -H "X-WP-Nonce: your-nonce"

Get Field Schema

Retrieve the generation schema for a specific field type. The schema describes which creation methods and options are available when configuring a field of this type in a template. This is useful for building dynamic template editors or for understanding what options you can pass in a field_config object.

Endpoint

GET /wp-json/wpfaker/v1/field-schema/{field_type}

Example Request

bash

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

Create Variant

Create a variant (child template) from an existing parent template. Variants inherit their parent's configuration and can selectively override specific fields. This supports template inheritance — you can maintain a base template and create lightweight variations without duplicating the entire configuration.

Endpoint

POST /wp-json/wpfaker/v1/templates/{id}/variant

Example Request

bash

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

INFO

Variants inherit all settings from their parent template. After creating a variant, use the Update Template endpoint to override specific fields. Only the overridden fields are stored on the variant — everything else is inherited at generation time through the effective config mechanism.

Get Effective Config

Retrieve the effective (merged) configuration for a template. For regular templates, this returns the same configuration as the Get Single Template endpoint. For variants, it merges the variant's overrides with the parent template's configuration, producing the complete configuration that would be used during generation. This is the endpoint to use when you need to see what a variant will actually generate.

Endpoint

GET /wp-json/wpfaker/v1/templates/{id}/effective-config

Example Request

bash

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

Get Stale Templates

Retrieve templates that need resynchronization because their underlying post type fields have changed. When you add, remove, or modify fields in your field plugin (ACF, Meta Box AIO, etc.), existing templates may reference fields that no longer exist or may be missing newly added fields. This endpoint identifies those templates so you can update them.

Endpoint

GET /wp-json/wpfaker/v1/templates/stale

Example Request

bash

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

Field Configuration Schema

This section documents the JSON schema used by the field_config and taxonomy_config objects in templates. Understanding this schema is essential for creating templates programmatically through the API or for passing inline field_config to the Generate Posts endpoint.

Field Modes

Every field in a template is configured with one of three modes that determine how its value is generated:

Mode	Description
`none`	The field is not populated during generation. Required fields revert to default generation behavior even when set to `none`.
`choose`	A value is selected from a predefined list that you provide. Selection can be random or rotational.
`create`	A value is generated automatically using FakerPHP methods appropriate for the field type.

Core Field Configuration

Core fields are WordPress's built-in post fields: title, content, excerpt, status, date, and author. Each core field supports specific creation methods.

json

{
  "core_fields": {
    "post_title": {
      "mode": "create",
      "create": {
        "method": "words",
        "word_count_min": 3,
        "word_count_max": 10
      }
    },
    "post_content": {
      "mode": "create",
      "create": {
        "method": "paragraphs",
        "paragraph_count_min": 3,
        "paragraph_count_max": 6,
        "include_html": true,
        "html_options": {
          "headings": true,
          "lists": true
        }
      }
    },
    "post_status": {
      "mode": "choose",
      "choose": {
        "values": ["publish", "draft"],
        "selection_mode": "random"
      }
    }
  }
}

Custom Field Configuration

Custom fields are populated according to their detected field type. The field_type property tells WPfaker what kind of data to generate, and the create object provides type-specific options.

json

{
  "custom_fields": {
    "price": {
      "mode": "create",
      "field_type": "number",
      "create": {
        "min": 10,
        "max": 500,
        "decimal_places": 2
      }
    },
    "category": {
      "mode": "choose",
      "field_type": "select",
      "choose": {
        "values": ["Electronics", "Clothing", "Books"],
        "selection_mode": "random"
      }
    },
    "internal_notes": {
      "mode": "none"
    }
  }
}

Taxonomy Configuration

Taxonomy configuration controls how taxonomy terms are assigned to generated posts. Each taxonomy can use the same three modes: none, choose, or create.

json

{
  "taxonomy_config": {
    "category": {
      "mode": "choose",
      "choose": {
        "term_ids": [5, 10, 15, 20],
        "count_min": 1,
        "count_max": 3,
        "selection_mode": "random"
      }
    },
    "post_tag": {
      "mode": "create",
      "create": {
        "count_min": 2,
        "count_max": 5,
        "use_existing": true
      }
    }
  }
}

When using choose mode for taxonomies, the term_ids array specifies the pool of terms to select from. The count_min and count_max values determine how many terms from the pool are assigned to each generated post.

When using create mode, WPfaker generates new taxonomy terms with locale-aware names. Setting use_existing to true allows the generator to also pick from terms that already exist in the taxonomy, mixing existing and new terms.

Database Schema

Templates are stored in the {prefix}_wpfaker_templates table. This is primarily an internal detail, but it can be useful for debugging or for understanding how template data is persisted.

sql

CREATE TABLE wp_wpfaker_templates (
  id bigint(20) unsigned NOT NULL AUTO_INCREMENT,
  name varchar(255) NOT NULL,
  description text,
  post_type varchar(100) NOT NULL,
  is_default tinyint(1) DEFAULT 0,
  is_system tinyint(1) DEFAULT 0,
  field_config longtext,
  taxonomy_config longtext,
  created_at datetime DEFAULT CURRENT_TIMESTAMP,
  updated_at datetime DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  PRIMARY KEY (id),
  KEY post_type (post_type),
  KEY is_default (is_default)
);

The field_config and taxonomy_config columns store JSON-encoded strings. The is_system flag is reserved for future use by WPfaker-provided starter templates.

WARNING

Modifying template data directly in the database bypasses validation. Always use the API endpoints to create, update, and delete templates.

Templates API ​

List Templates ​

Endpoint ​

Query Parameters ​

Example: List All Templates ​

Example: Filter by Post Type ​

Response ​

Get Single Template ​

Endpoint ​

Example Request ​

Response ​

Create Template ​

Endpoint ​

Parameters ​

Example Request ​

Response ​

Update Template ​

Endpoint ​

Parameters ​

Example Request ​

Response ​

Delete Template ​

Endpoint ​

Parameters ​

Example Request ​

Response ​

Set Default Template ​

Endpoint ​

Example Request ​

Response ​

Duplicate Template ​

Endpoint ​

Example Request ​

Response ​

Export Templates ​

Endpoint ​

Query Parameters ​

Example: Export Specific Templates ​

Example: Export by Post Type ​

Response ​

Import Template ​

Endpoint ​

Parameters ​

Example Request ​

Response ​

Get Fields for Post Type ​

Endpoint ​

Example Request ​

Response ​

Get Taxonomies for Post Type ​

Endpoint ​

Example Request ​

Get Taxonomy Terms ​

Endpoint ​

Query Parameters ​

Example: Search Terms ​

Get Field Schema ​

Endpoint ​

Example Request ​

Create Variant ​

Endpoint ​

Example Request ​

Get Effective Config ​

Endpoint ​

Example Request ​

Get Stale Templates ​

Endpoint ​

Example Request ​

Field Configuration Schema ​

Field Modes ​

Core Field Configuration ​

Custom Field Configuration ​

Taxonomy Configuration ​

Database Schema ​

Templates API

List Templates

Endpoint

Query Parameters

Example: List All Templates

Example: Filter by Post Type

Response

Get Single Template

Endpoint

Example Request

Response

Create Template

Endpoint

Parameters

Example Request

Response

Update Template

Endpoint

Parameters

Example Request

Response

Delete Template

Endpoint

Parameters

Example Request

Response

Set Default Template

Endpoint

Example Request

Response

Duplicate Template

Endpoint

Example Request

Response

Export Templates

Endpoint

Query Parameters

Example: Export Specific Templates

Example: Export by Post Type

Response

Import Template

Endpoint

Parameters

Example Request

Response

Get Fields for Post Type

Endpoint

Example Request

Response

Get Taxonomies for Post Type

Endpoint

Example Request

Get Taxonomy Terms

Endpoint

Query Parameters

Example: Search Terms

Get Field Schema

Endpoint

Example Request

Create Variant

Endpoint

Example Request

Get Effective Config

Endpoint

Example Request

Get Stale Templates

Endpoint

Example Request

Field Configuration Schema

Field Modes

Core Field Configuration

Custom Field Configuration

Taxonomy Configuration

Database Schema