Bypassing API Limitations: Adding the Yoast SEO Main Category to the WordPress REST API (with Full Code)

all SEO The game ultimately comes down to whether the "signals" are clear or not.
If the categorization signals are confusing, breadcrumbs can confuse search engines like a maze.
Yoast SEO's "Main Category" feature is precisely the key to solving this problem.
The problem is:Wordpress This field is not enabled in the native REST API.
Therefore, we must take matters into our own hands, break through the API limitations, and add the main category to the REST API.

Why add the Yoast main category to the REST API?

Many people think that REST APIs are just tools for developers, but in content automation and... AI In a driven writing scenario, it is the core channel.
If the main category cannot be set via API, the article hierarchy will lose its uniqueness.
this means:

• The breadcrumb path may have multiple branches.
• Google's structured data parsing can produce ambiguity.
• Page weight is diluted across different categories.

According to Google's official documentation, breadcrumbs must maintain a single, clear path; otherwise, they will affect indexing efficiency.
This is not an exaggeration; it is a signal directly related to the quality of the page.

Registering meta fields: a standard solution that solves the problem once and for all.

The solution is actually quite elegant: simply register the main category meta field of Yoast and make it available to the REST API.
In this way, any API call can directly read and write this field.

code show as below:

<?php
add_action('init', function () {
    register_post_meta('post', '_yoast_wpseo_primary_category', [
        'type'              => 'string',
        'single'            => true,
        'show_in_rest'      => true,
        'auth_callback'     => function () {
            return current_user_can('edit_posts');
        },
    ]);
});

The purpose of this code is:

• Register meta fields _yoast_wpseo_primary_category.
• Open REST APIIt allows reading and writing via the interface.
• Permission controlOnly users with article editing privileges can operate this feature.

How do I deploy mu-plugin?

Put this code in mu-plugin This ensures it always works.

path:

wp-content/mu-plugins/yoast-primary-rest.php

Why choose mu-plugin?
Because it is not theme-dependent and cannot be disabled, it is a "one-and-done" solution.
WordPress will load the file automatically as long as it exists.

Verification: Test directly using the curl command.

Once deployed, no restart or additional configuration is required.
It will appear in the meta field of the REST API. _yoast_wpseo_primary_category.

Verification command:

curl -s -u "用户名:应用密码" -X POST \
  -H "Content-Type: application/json" \
  -d '{"meta":{"_yoast_wpseo_primary_category":"33"}}' \
  "https://www.chenweiliang.com /wp-json/wp/v2/posts/{post_id}"

among them:

• 33 It is a category ID.
• {post_id} It is the article ID.
• 用户名:应用密码 It is a password authentication for WordPress applications.

After execution, the article's main category will be updated to the specified category.

Actual effect: Unification of SEO signals

Once the main category can be set via API, the entire SEO signal chain will become clear:

• The breadcrumb path is unique.
• Structured data is unambiguous.
• Google's crawler can quickly identify page hierarchy.

This is not only a technological optimization, but also a stabilizer for the content ecosystem.
In large-scale content production scenarios, unifying the main categories can significantly reduce indexing errors.

Search Engine Land's 2025 article points out:

“Breadcrumbs are not just navigation aids; they are signals of hierarchy that search engines rely on.”

The official Yoast documentation also clearly states:

“Primary category ensures that your content has a single, clear path in breadcrumbs.”

These viewpoints all emphasize the importance of the main category.
By extending the REST API, we are fully integrating this functionality into the automated process.

Conclusion

The essence of SEO is to enable machines to understand human-generated content.
The main category is the anchor of order in this communication.
If keywords are the symbols of language, then breadcrumbs are the maps of structure.
Without a map, a search engine can only wander around in a maze.

Therefore, breaking through API limitations and adding the Yoast main category to the REST API is not just a development technique, but also a strategic choice.
It gives your content greater visibility and stronger signal stability in the era of generative search engines.

Only by mastering order can one control power.
This is the true intersection of technology and SEO.