wp-rest-api

Transmit assets that already exist — block markup, CSS, and animation JS — to a WordPress site over /wp-json/, using curl and an admin Application Password. This is the last mile that used to be a copy-paste into the Code Editor. The markup is generated elsewhere; this skill transmits bytes unchanged and tells you the truth about what the site did with them.

Everything needs curl and jq (1.6+), plus grep and diff for the verification steps. Nothing else — no MCP server, no CLI, no SSH, no database access.

1 · Preflight — three reads before any write

Run all three. Do not skip one because the last session passed.

From request 3, record two values and carry them for the whole session:

• stylesheet — the active theme slug (e.g. twentytwentyfive).
• _links['wp:user-global-styles'][0].href — an absolute URL whose last path segment is the record id. Resolve it every time. Two sites running identical WordPress and theme versions returned /wp/v2/global-styles/4 and /wp/v2/global-styles/6. Never hardcode it and never carry an id between sites or between runs.

Also take an unauthenticated GET / and record the HTTP status and body byte count. That is the before-picture for §6. It costs one request and it catches a catastrophe.

Branch on the JSON code field and the HTTP status, never on the message prose. WordPress REST errors are {code, message, data:{status}} and code is stable across versions.

2 · Credentials

HTTP Basic with an admin Application Password, which curl -u "$WP_USER:$WP_APP_PASSWORD" builds for you. Put the value in a gitignored .env and reference the variable, so the shell expands it below the transcript:

export WP_BASE_URL="https://example.com"
export WP_USER="admin"
TMPDIR="${TMPDIR:-/tmp}"   # every example below writes its scratch files here
# WP_APP_PASSWORD comes from the gitignored .env

The username is not protected by any of this. The site URL and username sit in the transcript in the clear. Say that once, plainly, rather than glossing it.

3 · Push the block markup

This skill transmits bytes unchanged. Do not "fix" markup on the way through, and do not validate by eye — if the markup is questionable, report what looks wrong and hand it back.

Body shape — nothing else unless the user asked for it:

{ "title": "My Page", "slug": "my-page", "content": "<block markup, byte for byte>" }

Set template explicitly for a landing page. Leaving template as "" resolves to the theme's default page template, which on most block themes renders the site header and an <h1> of the page title above the design — so a landing page's own brand bar shows up third, under two things the user did not ask for.

status decision table. A default status: "draft" sent on every write silently demotes live pages while every verification step reports green. This is a known critical failure mode.

Build the body by JSON-encoding the file rather than pasting markup into a shell string, and send it with --data-binary @file, never -d @file — -d strips newlines out of a file argument. The commands are in reference/endpoints.md.

4 · Push the CSS

On a block theme, CSS goes in styles.css on the user global-styles record. That is the whole route, and preflight step 3 already told you whether it exists. On a classic theme there is no such record: say so and stop, or — if the user asks for that instead — ship the CSS as a PHP snippet that enqueues a stylesheet (§5, reference/code-snippets.md), and never a *-css scope, which is Pro-only and silently never runs.

Never smuggle a <style> block into the markup as raw HTML. A core/html block carrying CSS or JS is non-portable, depends on the author's unfiltered_html capability, and cannot be called validated markup.

The write is three steps, because the id is not guessable and the record must be merged:

Deep-merge, never replace. This is the single most dangerous operation in the skill. Every sibling under settings, under settings.layout, and under styles must be read from the live GET and written back untouched. A naive replace destroys the site's entire colors, typography and variations record. The commands, including the [] type guard the merge needs, are in reference/endpoints.md.

Strip every < from the CSS before you push it

A single < anywhere in the CSS body — including inside a comment — makes Site Editor → Styles → Additional CSS reject the whole value with "The custom CSS is invalid. Do not use <> markup."

Nothing else complains:

So the push looks green, the page looks right, and the human who later opens Styles finds their stylesheet condemned. One < anywhere, including inside a comment, is enough.

Things to tell the user when you take this route:

• It is site-wide, not page-scoped. Prefix every selector with a page class so it cannot leak.
• It is per theme. A theme switch leaves it behind.
• GET /wp/v2/global-styles/<id>/revisions is the durable manual undo. Name it before writing.
• Replacing styles.css wholesale means a second page's CSS overwrites the first. A marker-comment convention (/* --- page:foo --- */ … /* --- /page:foo --- */) around each page's section would make sections individually replaceable — a proposal, not a tested convention. Say so.
• Multi-line stylesheets survive the round trip byte-for-byte and do reach the editor canvas, and there is no practical length ceiling (tested well past any realistic stylesheet size). Size is not what will bite you; a single < is. Read the record back and compare every time.

5 · Push PHP or JS — the snippet route

WordPress core has no REST route that runs your code. The Code Snippets plugin adds one (code-snippets/v1), and that is the path for an animation init, a CDN enqueue, a hook or a filter. Read reference/code-snippets.md before the first snippet request, and reference/animation.md as well if the payload is a GSAP or scroll animation.

This route writes executable code to the user's site. Three rules that are not optional:

Capability probe, before anything else: GET /wp-json/ and look for code-snippets/v1 in namespaces[]. Absent means the plugin is not installed or not active — ask, do not install silently. If the user authorises the install, reference/troubleshooting.md covers the activation failure that looks like a plugin bug and is not one.

6 · Verify

Four steps. The last one is the only one that actually proves anything.

Step 4 is not optional and you cannot do it. A frontend screenshot passes while the editor shows a recovery prompt, a clamped narrow canvas, or unstyled content — those are exactly the failure modes in reference/gutenberg-traps.md. Report the two URLs and ask for a look:

• frontend: the link field from the write response
• editor: $WP_BASE_URL/wp-admin/post.php?post=<id>&action=edit

A dry run, a fixture and a clean validator report prove nothing here. A byte-exact read-back and a green frontend both pass while the editor is broken, which is why step 4 exists.

7 · What this does not do — say so and stop

Name the object, name the capability that does not exist here, hand the decision to the human, and do not improvise a bypass. There is nothing between you and curl, which is exactly why this rule matters more here than in a tool with guardrails of its own.

If the user authorises going around this skill, say plainly what is lost for those bytes: the read-back comparison, the before/after health picture, and the deep-merge guard on the global-styles record. None of it applies to a hand-rolled request.