Hooks, Filters and REST API

Hooks Filters And Rest Api is the focus of this documentation page. WordPress filters for prompts, parameters, and custom actions. Full REST API reference. Follow the sections below to configure the feature and use it in your WordPress workflow.

SmartyPress AI Engine provides WordPress filters, actions, a REST API, and one JavaScript filter for developers to customize and extend the plugin.

Key Filters

smartypress_ai_prompt_{action}

Customize the prompt for any Magic Wand action. Receives the built prompt and arguments.

add_filter( 'smartypress_ai_prompt_generateTitle', function( $prompt, $arguments ) { return 'Create a clickable, SEO title (max 60 chars) for: ' . ($arguments['context'] ?? '');
}, 10, 2 );

smartypress_ai_wand_params

Modify AI generation parameters (temperature, max_tokens, model) for Magic Wand actions.

add_filter( 'smartypress_ai_wand_params', function( $params, $action ) { if ( $action === 'enhanceText' ) { $params['temperature'] = 0.5; $params['max_tokens'] = 3000; } return $params;
}, 10, 2 );

smartypress_ai_wand_features

Add custom Magic Wand actions or modify existing ones.

add_filter( 'smartypress_ai_wand_features', function( $features ) { $features['generateFAQ'] = array( 'label' => 'Generate FAQ', 'sublabel' => 'Q&A Section', 'arguments' => array( 'postId', 'text', 'prompt' ), 'where' => 'blockContext', 'mode' => 'replace', 'default_prompt' => 'Generate 5 FAQ items based on: {TEXT}', 'placeholder' => 'Enter topic...', ); return $features;
} );

Content Plan Filters

Plan-Based Content Generation runs in two AI steps — building an editable plan structure, then filling it with content — plus optional per-section drafting. Each step exposes its own filter.

• smartypress_ai_content_plan_schema_request_params — modify the AI request parameters used to build the editable plan structure (phase 1)
• smartypress_ai_content_plan_prompt — modify the prompt used to fill the plan with content (phase 2)
• smartypress_ai_content_plan_request_params — add parameters to the phase 2 plan-fill API request
• smartypress_ai_content_plan_seo_analysis_enabled — control whether competitor research from the SEO Analysis module is attached to a plan

After a plan is filled, the Content Generator also fires smartypress_ai_content_plan_research_generated whenever competitor research data (headings or keywords) was attached to the plan. The SEO Analysis module listens to this action to log research usage; use it to sync research data with an external system.

add_filter( 'smartypress_ai_content_plan_seo_analysis_enabled', function( $enabled, $provider_name, $model, $plan_context ) { // Only attach competitor research when OpenRouter is selected. return 'openrouter' === $provider_name;
}, 10, 4 ); add_action( 'smartypress_ai_content_plan_research_generated', function( $plan, $plan_context ) { error_log( 'Plan research attached for topic: ' . ( $plan_context['topic'] ?? '' ) );
}, 10, 2 );

Content Generation Extension Hooks

Bulk generation for post types with special fields (for example WooCommerce products) is built on a small extension interface, SmartyPress_AI_Post_Type_Extension_Interface. Register an extension through smartypress_ai_content_post_type_extensions and the registry calls it at every generation step for matching post types.

add_filter( 'smartypress_ai_content_post_type_extensions', function( array $extensions ) { $extensions[] = new My_Custom_Post_Type_Extension(); return $extensions;
} );

Once an extension is registered, these plain filters and one action run around it for every generated item:

• smartypress_ai_content_generation_rules — modify the combined generation rules (prompt hints) for a post type
• smartypress_ai_content_seo_rules — modify the combined SEO rules for a post type
• smartypress_ai_content_item_context — modify the extra context text merged into the generation prompt for a queue item
• smartypress_ai_content_prepared_post_data — modify the post fields right before wp_insert_post() runs
• smartypress_ai_content_after_post_persisted — action, fires after a generated post and its extension metadata are saved

SEO Metadata Filters

These filters apply whenever the Content Generator writes SEO metadata (title, description, slug, keyword) for a newly generated post — single, bulk, or plan-based — regardless of which SEO plugin is active.

smartypress_ai_seo_metadata_before_write

Modify SEO metadata (title, description, slug, keyword) before it is saved to the post.

add_filter( 'smartypress_ai_seo_metadata_before_write', function( $metadata, $post_id ) { // Ensure brand name is always in the SEO title if ( strpos( $metadata['title'], 'MyBrand' ) === false ) { $metadata['title'] .= ' | MyBrand'; } return $metadata;
}, 10, 2 );

• smartypress_ai_seo_metadata_adapters — add, remove, or replace the SEO plugin adapters that receive generated metadata (built-in: WordPress slug, Rank Math, Yoast SEO, AIOSEO)
• smartypress_ai_seo_metadata_adapter_enabled — enable or disable one specific adapter for a given post
• smartypress_ai_bulk_seo_optimization_prompt — modify the AI prompt used to generate SEO metadata during bulk/legacy generation
• smartypress_ai_bulk_seo_optimization_enabled — disable the AI SEO metadata step for bulk/legacy generation
• smartypress_ai_seo_content_deterministic_fallback_enabled — disable the non-AI keyword-placement fallback used when AI-based metadata is unreliable
• smartypress_ai_content_output_format — force the generated content format: gutenberg, html, or legacy_markdown

SEO Optimization Filters

These filters apply only to the SEO Optimization module, which fixes SEO issues detected by Rank Math, Yoast SEO, or AIOSEO on an existing post via the /seo-optimization/* endpoints below.

smartypress_ai_seo_content_strategies

Add, remove, or modify the list of content optimization strategies used by SEO Optimization.

add_filter( 'smartypress_ai_seo_content_strategies', function( $strategies ) { // Remove the TOC strategy unset( $strategies['table_of_contents'] ); return $strategies;
} );

Provider Filters

smartypress_ai_openrouter_request_params

Modify request parameters sent to OpenRouter API.

add_filter( 'smartypress_ai_openrouter_request_params', function( $params ) { $params['top_p'] = 0.9; return $params;
} );

• smartypress_ai_openrouter_web_search_params — modify the web-search parameters sent for Sonar/online OpenRouter models
• smartypress_ai_model_capabilities — override the capability flags (vision, web search, JSON mode, etc.) resolved for any provider/model pair
• smartypress_ai_openrouter_model_capabilities — override capability flags specifically for OpenRouter models
• smartypress_ai_openrouter_text_fallback_models — change the fallback OpenRouter text model list used when the configured model is unavailable

Bulk Generation Filters

smartypress_ai_bulk_max_topics

Change the maximum number of topics for bulk generation (default: 50).

add_filter( 'smartypress_ai_bulk_max_topics', function() { return 100;
} );

• smartypress_ai_bulk_estimated_input_tokens — override the estimated input tokens per item used for bulk cost calculation (default: 3500)
• smartypress_ai_bulk_estimated_output_tokens — override the estimated output tokens per item used for bulk cost calculation (default: 2500)

Module and Admin Extension Hooks

These hooks control which modules load and let other plugins extend the SmartyPress AI admin screens.

• smartypress_ai_register_modules — filter the list of available modules before they load
• smartypress_ai_pre_load_module — action, fires right before a module’s files are loaded
• smartypress_ai_module_loaded — action, fires after a module has finished loading
• smartypress_ai_module_toggled — action, fires after a module is enabled or disabled from the Components screen
• smartypress_ai_module_{module_id}_metadata — override a module’s name, description, or icon shown on the Components screen
• smartypress_ai_module_{module_id}_settings — action, fires while a module registers its settings; used by Content Generator, Image Generator, SEO Analysis, and SEO Optimization
• smartypress_ai_admin_routes — add or override React admin routes (path, component, title, icon)
• smartypress_ai_admin_notices — filter the registered admin notice definitions
• smartypress_ai_register_admin_notices — action, register additional admin notices

add_filter( 'smartypress_ai_register_modules', function( array $modules ) { // Prevent a module from loading at all, regardless of the Components screen. unset( $modules['seo_analysis'] ); return $modules;
} );

Frontend Filters (JavaScript)

The Plan-Based Content Generation wizard exposes one @wordpress/hooks filter so other plugins can inject UI above the topic field — this is how the SEO Analysis module adds its Competitor Analysis Assistant.

smartypress.contentGenerator.topicInput.beforeTopicField

Renders extra markup above the topic input in the content plan wizard. Receives the currently rendered node and a context object (settings, pluginSettings, providerModels, topic, setTopic, research, setResearch).

import { addFilter } from '@wordpress/hooks';
import { createElement, Fragment } from '@wordpress/element'; addFilter( 'smartypress.contentGenerator.topicInput.beforeTopicField', 'my-plugin/topic-field-note', ( rendered, context ) => createElement( Fragment, {}, rendered, createElement( 'p', {}, 'Current topic: ' + context.topic ) )
);

REST API

All endpoints use namespace smartypress/v1/ and require authentication via WordPress nonce (or another authenticated REST transport). There are several dozen endpoints in total, grouped below by purpose.

Settings (requires manage_options)

Modules (requires manage_options)

Token Usage (requires manage_options)

Dashboard Helpers (requires manage_options)

Content Generation (requires edit_posts)

Bulk Generation (requires publish_posts, except /bulk-prompts which requires edit_posts)

Image Generation (requires edit_posts)

Image ALT Generator (requires upload_files, except settings updates which require manage_options)

SEO Optimization (requires edit_post on the target post, except keyword-slug which requires edit_posts)

SEO Analysis (requires edit_posts)

Hooks Filters And Rest Api Workflow Checklist

The hooks filters and rest api workflow should be treated as a repeatable process, not a one-time setting. Start by confirming that the SmartyPress AI Engine module related to this page is enabled, then check the default provider, model, language, and post type settings before you run the feature on production content. This keeps generated output predictable and makes it easier to compare results between OpenAI, DeepSeek, Anthropic Claude, OpenRouter, Yandex GPT, and GigaChat.

Use this checklist whenever you document, test, or train another editor on Hooks, Filters and REST API. It helps keep the setup aligned with WordPress permissions, Rank Math SEO fields, and the editorial workflow used by your site. If a result looks different from what you expected, repeat the same checklist with a smaller prompt and a lower temperature before changing global settings.

1. Confirm that the required SmartyPress AI module is enabled in the Components screen.
2. Open Settings and verify that the selected provider has a valid API key and a tested connection.
3. Choose the model that fits the task: fast models for drafts, premium models for final marketing copy, and web-search models for research.
4. Review the output language, temperature, max tokens, and prompt variables before generating content.
5. Save the result as a draft first, then review headings, links, facts, and SEO fields before publishing.

Recommended Settings

For most hooks filters and rest api tasks, start with a balanced model such as GPT-4o Mini, GPT-4o, DeepSeek V4 Flash, Claude Sonnet, or a carefully selected OpenRouter model. Keep temperature around 0.5 to 0.8 for documentation and tutorials, because these pages need clarity more than experimentation. Increase temperature only when you need more creative headlines, introductions, or alternative wording.

Use a clear default language and keep prompt variables consistent across articles. For documentation pages, a neutral or professional writing tone usually works best. If the generated result is too short, increase the number of sections or paragraphs per section rather than asking the model to “write more” after the fact. Structured settings create more stable output and make Hooks, Filters and REST API easier to reproduce later.