Automate Your Yoast Meta Description (REST API + Code Snippets)

The Yoast meta description API does not exist as a write endpoint. Specifically, Yoast SEO ships its REST surface as read-only, so a POST to update a meta description silently no-ops. However, a 22-line Code Snippets PHP block solves this. Register the Yoast fields with show_in_rest=true. As a result, the standard WordPress endpoint accepts atomic writes.

This post ships the full snippet. Furthermore, it walks through the four-field atomic POST. Additionally, it addresses the indexables caveat that trips up most automation builds. As a result, you get bulk Yoast writes from Python — no extra plugins, no manual paste in WordPress admin.

The Yoast meta description API blocker explained

Out of the box, Yoast does not expose its SEO fields to the WordPress REST endpoint. Specifically, Yoast SEO publishes a read-only REST surface. As a result, a POST to /wp/v2/posts/<id> with a meta payload returns 200 OK, but the field stays empty in the editor. The reason: Yoast does not register its post-meta keys with show_in_rest=true. Furthermore, the WordPress REST controller silently drops every meta key it does not recognize.

This catches every developer once. As a result, the first attempt at automation looks like it worked. The API call succeeded, the post saved. However, the meta description box in Yoast remains blank. Furthermore, the fix is not in the POST payload. It is one PHP hook that exposes the fields to REST. Yoast’s own developer portal confirms the REST API is read-only. In effect, it is for retrieval, not writes.

The 22-line Code Snippets fix (full PHP block)

The fix is a single PHP snippet that registers six Yoast post-meta keys with show_in_rest=true. Specifically, the hook fires on init and loops over post types. Each Yoast field gets a string type and an edit_posts auth callback. As a result, the WordPress REST endpoint accepts Yoast writes once the snippet is active.

add_action('init', function () {
    $fields = [
        '_yoast_wpseo_metadesc',
        '_yoast_wpseo_title',
        '_yoast_wpseo_focuskw',
        '_yoast_wpseo_focuskeywords',
        '_yoast_wpseo_canonical',
        '_yoast_wpseo_linkdex',
    ];
    foreach (['post', 'page', 'portfolio'] as $post_type) {
        foreach ($fields as $field) {
            register_post_meta($post_type, $field, [
                'show_in_rest'  => true,
                'single'        => true,
                'type'          => 'string',
                'auth_callback' => function () {
                    return current_user_can('edit_posts');
                },
            ]);
        }
    }
});

Code Snippets is the safe path here. Furthermore, the plugin auto-deactivates any snippet that throws a PHP error at save. As a result, a typo never crashes the live site. Additionally, this is reversible in two clicks from WordPress admin. The WordPress.org plugin directory lists Code Snippets at over one million active installs. In effect, that is the trust signal most non-technical site owners need. For more on the plugin path, see the Code Snippets WordPress tutorial.

Extending the snippet to custom post types

Each custom post type needs its own register_post_meta call. Specifically, the function is per-post-type. Registering Yoast fields for post does not expose them on portfolio or any other CPT. As a result, a snippet that only covers post + page silently no-ops on a portfolio API write.

# Enumerate every CPT exposed by the REST API
GET https://example.com/wp-json/wp/v2/types

# Returns rest_base values: post, page, portfolio, attachment, product, ...

Run GET /wp-json/wp/v2/types to list every active post type on the site. The official WordPress reference covers the full parameter list. In particular, watch for plugins that register their own CPTs. WooCommerce products, Elementor templates, custom plugin types — each needs the loop. Furthermore, the snippet above handles three post types. The same pattern scales to any number — just extend the array.

Writing four Yoast fields in one Python POST

One POST request can write all four Yoast fields atomically. Specifically, the meta description, focus keyword, additional keyphrases, and SEO title live under meta. As a result, the entire SEO setup for a post lands in a single HTTP call.

import requests
from requests.auth import HTTPBasicAuth

WP_URL = "https://example.com"
auth = HTTPBasicAuth("claude-bot", "K3pW Q9mz X2dV nB7H jL4r Y6sT")

headers = {
    "User-Agent": (
        "Mozilla/5.0 (Windows NT 10.0; Win64; x64) "
        "AppleWebKit/537.36 (KHTML, like Gecko) "
        "Chrome/126.0 Safari/537.36"
    ),
    "Content-Type": "application/json",
}

payload = {
    "meta": {
        "_yoast_wpseo_metadesc": "Automate Yoast meta writes from Python in five "
                                  "lines: register the field, then POST four values at once.",
        "_yoast_wpseo_focuskw": "automate Yoast meta description",
        "_yoast_wpseo_title": "Automate Yoast Meta via REST: A 22-Line Fix",
    },
}

r = requests.post(
    f"{WP_URL}/wp-json/wp/v2/posts/1847",
    auth=auth, headers=headers, json=payload,
)
print(r.status_code, r.json().get("meta", {}))

Notice the User-Agent header. In particular, Cloudflare blocks the default python-requests user-agent with a 1010 error. As a result, a real browser User-Agent is mandatory on every request. Furthermore, the auth pattern uses an Application Password, not the WP login password. For the full auth walkthrough, see how to connect WordPress to Claude.

Yoast Premium additional keyphrases via the API

Yoast Premium’s additional keyphrases field accepts a JSON array of objects, not a flat string. Specifically, the field is _yoast_wpseo_focuskeywords (with an s). Each object needs a keyword key and a score key. As a result, the payload format trips up most first attempts. Passing a comma-separated string returns 200 OK, but the keyphrases list stays empty.

import json

additional = json.dumps([
    {"keyword": "automate Yoast meta description", "score": ""},
    {"keyword": "expose Yoast fields to REST",     "score": ""},
    {"keyword": "register_post_meta yoast",        "score": ""},
])

payload = {
    "meta": {
        "_yoast_wpseo_focuskeywords": additional,
    },
}

The score field stays empty for API writes. In particular, Yoast computes the per-keyphrase score in JavaScript at editor save. As a result, the keyphrases appear in the Yoast UI immediately. However, the score column reads empty until the post is opened and saved manually. Above all, this is the right trade-off for bulk operations. Dozens of posts each get three correctly-stored additional keyphrases in seconds. The score column populates the next time anyone clicks Update.

The indexables caveat: why the SEO score does not recompute

Yoast computes the overall SEO score in client-side JavaScript at editor save. Specifically, _yoast_wpseo_linkdex stores the green-orange-red 0 to 100 score. However, that field is only written when the block editor saves the post and Yoast’s analyzer runs. As a result, posts edited via REST API alone show empty SEO scores in the Posts list.

The workaround takes one click. Specifically, open the post in the WordPress block editor and click Update. Yoast re-runs its analyzer and writes _yoast_wpseo_linkdex to the database. Furthermore, Yoast also maintains an “indexables” table that mirrors the SEO data in an optimized form. As a result, the API write goes to wp_postmeta. Yoast’s runtime reads from indexables. The editor save reconciles the two.

The long-term fix is a Python-side Yoast scoring engine. Yoast’s analyzer is open-source at Yoast/wordpress-seo. As a result, the same algorithms can run in Python and write the score directly. Until then, the editor save remains the source of truth.

Verifying the Yoast meta description API write landed

Verification is one line of Python: read the post back and assert the meta key. Specifically, GET /wp/v2/posts/<id>?context=edit&_fields=meta returns every registered meta key. In effect, an empty value here means the snippet is not registered for that post type.

r = requests.get(
    f"{WP_URL}/wp-json/wp/v2/posts/1847?context=edit&_fields=meta",
    auth=auth, headers=headers,
)
meta = r.json().get("meta", {})
assert meta.get("_yoast_wpseo_metadesc"), "Snippet not active for this post type"
print("Yoast metadesc landed:", meta["_yoast_wpseo_metadesc"][:60])

Run this verification on every post pushed via the API. In particular, an empty meta._yoast_wpseo_metadesc after a 200 OK is the canary for a missing register_post_meta call. Furthermore, this check belongs in the publishing pipeline. As a result, regressions get caught once and fixed once.

Frequently asked questions about the Yoast meta description API

Yoast Premium and validation questions

The blocker is one missing PHP hook, not a missing REST endpoint. Specifically, register the fields, send one POST, verify with one GET. As a result, the entire SEO setup for a post takes seconds. Furthermore, the same pattern scales to bulk-fixing 50 or 500 posts in one script run. In effect, that is the workflow behind a three-hour cleanup of 1,057 issues. Above all, every post can now ship with its meta description, focus keyword, and additional keyphrases in place. Additionally, the same pattern handles Ahrefs warnings and Yoast Premium redirects from one pipeline.

— Lukas