Skip to content

Templates API ​

Templates are the mechanism through which Faker Studio 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/faker-studio/v1/templates

Query Parameters ​

ParameterTypeRequiredDefaultDescription
post_typestringNo—Filter templates to those targeting a specific post type
is_systembooleanNo—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/faker-studio/v1/templates" \
  -H "X-WP-Nonce: your-nonce"

Example: Filter by Post Type ​

bash
curl "https://yoursite.com/wp-json/faker-studio/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/faker-studio/v1/templates/{id}

Example Request ​

bash
curl "https://yoursite.com/wp-json/faker-studio/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 (Premium) ​

Not available in Faker Studio Lite

This endpoint returns a 403 (lite_readonly) in Faker Studio Lite. Lite templates are auto-generated; only Update Template (General fields) works.

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

Parameters ​

ParameterTypeRequiredDescription
namestringYesDisplay name for the template
descriptionstringNoA brief description explaining the template's purpose
post_typestringYesThe post type this template targets. Cannot be changed after creation.
is_defaultbooleanNoSet 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_configobjectNoField configuration object containing core_fields and custom_fields settings
taxonomy_configobjectNoTaxonomy 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/faker-studio/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 ​

Faker Studio Lite

Lite accepts this request but silently strips taxonomy_config, field_config, and config_overrides — only General-tab fields (name, post type, status, image provider, locale, variation profile) are saved.

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/faker-studio/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/faker-studio/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 (Premium) ​

Not available in Faker Studio Lite

This endpoint returns a 403 in Faker Studio Lite.

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/faker-studio/v1/templates/{id}

Parameters ​

ParameterTypeRequiredDescription
new_default_idintegerNoID 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/faker-studio/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/faker-studio/v1/templates/{id}/default

Example Request ​

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

Not available in Faker Studio Lite

This endpoint returns a 403 in Faker Studio Lite.

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/faker-studio/v1/templates/{id}/duplicate

Example Request ​

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

Not available in Faker Studio Lite

Exporting templates is not available in Faker Studio Lite.

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/faker-studio/v1/templates/export

Query Parameters ​

ParameterTypeRequiredDescription
idsarrayNoArray of template IDs to export. Omit to export by post type instead.
post_typestringNoExport all templates targeting this post type. Ignored when ids is provided.

Example: Export Specific Templates ​

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

Faker Studio Lite

Lite can import one template at a time. Importing multiple templates in a single request (batch import) requires Premium and returns a 403 in Lite.

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/faker-studio/v1/templates/import

Parameters ​

ParameterTypeRequiredDescription
templatesarrayYesArray of template objects from the export endpoint's templates array

Example Request ​

bash
curl -X POST "https://yoursite.com/wp-json/faker-studio/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/faker-studio/v1/templates/fields/{post_type}

Example Request ​

bash
curl "https://yoursite.com/wp-json/faker-studio/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/faker-studio/v1/templates/taxonomies/{post_type}

Example Request ​

bash
curl "https://yoursite.com/wp-json/faker-studio/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/faker-studio/v1/taxonomies/{taxonomy}/terms

Query Parameters ​

ParameterTypeRequiredDefaultDescription
taxonomystringYes—The taxonomy slug to retrieve terms from
searchstringNo—Filter terms by name (partial match)
parentintegerNo—Filter to direct children of this term ID. Use 0 for top-level terms.
per_pageintegerNo100Maximum number of terms to return

Example: Search Terms ​

bash
curl "https://yoursite.com/wp-json/faker-studio/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/faker-studio/v1/field-schema/{field_type}

Example Request ​

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

Create Variant (Premium) ​

Not available in Faker Studio Lite

This endpoint returns a 403 in Faker Studio Lite.

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/faker-studio/v1/templates/{id}/variant

Example Request ​

bash
curl -X POST "https://yoursite.com/wp-json/faker-studio/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/faker-studio/v1/templates/{id}/effective-config

Example Request ​

bash
curl "https://yoursite.com/wp-json/faker-studio/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/faker-studio/v1/templates/stale

Example Request ​

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

ModeDescription
noneThe field is not populated during generation. Required fields revert to default generation behavior even when set to none.
chooseA value is selected from a predefined list that you provide. Selection can be random or rotational.
createA 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 Faker Studio 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, Faker Studio 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}_faker_studio_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_faker_studio_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 Faker Studio-provided starter templates.

WARNING

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