Wordpress Api Connector

---
name: wordpress-api-connector
description: Connect an AI agent to WordPress with an application password — the 4-point pre-check, the 6 steps, the pre-flight auth call, and the fixes for 403, 401, and rest_no_route. Use when asked to connect WordPress, get a WordPress API key or application password, fix a 401 or 403 from wp-json, set up auto-publishing, find an author or category ID, or someone says 'the agent can't publish to my site'. For the rest of the key wallet, see env-and-keys-setup. For the publish pipeline itself, see the SEO skills.
metadata:
  version: 1.0.0
---

# WordPress API connector

The part that stops most students. **Fifteen minutes, done once, and the agent
can publish forever.** WordPress's application password is a separate 24-character
login just for the agent — revocable in ten seconds without touching your real
password, which is the whole reason it exists.

The habit this skill exists to teach: **pre-flight, then fly.** One cheap auth
call before any run — an agent that discovers a broken password after writing
2,500 words has wasted your money.

## Before you start — the 4-point check

| Check | Why |
| --- | --- |
| WordPress 5.6 or newer | Application passwords are built in since 5.6 |
| The site runs HTTPS | WordPress hides the application-password screen on plain HTTP |
| Self-hosted WordPress (wordpress.org) | Not a free wordpress.com plan |
| Your user has Editor or Administrator role | Lower roles cannot publish via API |

## Step 1 — Generate the application password

1. Go to `https://yourdomain.com/wp-admin/profile.php`, scroll to
   **Application Passwords**.
2. Name it (e.g. `Claude SEO Agent`), click **Add New Application Password**.
3. **Copy it now — it is shown exactly once.** Format `abcd efgh ijkl mnop qrst
   uvwx`. **Keep the spaces; they are part of the password.**
4. Paste into `.env` as `WP_APPLICATION_PASSWORD`.

## Step 2 — Pre-flight before you trust anything

One command. If it returns your user object, everything else will work:

```bash
curl -s -u "you@yourdomain.com:xxxx xxxx xxxx xxxx xxxx xxxx" \
  -A "Mozilla/5.0" \
  "https://yourdomain.com/wp-json/wp/v2/users/me?context=edit"
```

The `id` in the response is your `WP_AUTHOR_ID`. Every agent run repeats this
call first — it costs nothing and says in one second whether the next twenty
minutes of work has anywhere to land.

## Step 3 — Pull the IDs the agent works in

The API works in IDs, not names. Once, into `.env`:

```
GET /wp-json/wp/v2/users?search=<your name>      → WP_AUTHOR_ID
GET /wp-json/wp/v2/categories?per_page=100       → DS_DEFAULT_CATEGORIES
GET /wp-json/wp/v2/tags?per_page=100             → tag IDs as needed
```

Without an explicit author ID, posts publish under the default admin — which
throws away the author credibility signal every post was meant to build.

## Step 4 — Know the publish order (for whoever builds the pipeline)

Six calls, in this exact order, because each depends on the last: duplicate-slug
check → media upload (+ alt text) → get-or-create tags → create post (with
explicit `author`) → SEO-plugin metadata call → verify the live URL. Note:
Rank Math has its **own** endpoint (`/wp-json/rankmath/v1/updateMeta`) — writing
its fields to the standard post meta silently does nothing.

## Output

```
# WordPress connection: <domain>

4-point check: version ✓ · HTTPS ✓ · self-hosted ✓ · role ✓
.env: WP_SITE_URL / WP_USERNAME / WP_APPLICATION_PASSWORD (spaces kept) /
      WP_AUTHOR_ID=<n> / DS_DEFAULT_CATEGORIES=<ids>
Pre-flight: users/me → 200, id=<n>, name=<who>
Revocation drill: wp-admin → Profile → Application Passwords → Revoke (10 seconds)
```

## When it breaks

| What you see | What it means | The fix |
| --- | --- | --- |
| 403 Forbidden | Security plugin or host WAF blocking the default python-requests user agent — **not your credentials** | Send a browser User-Agent (`Mozilla/5.0`) on every call. The single most common blocker |
| 401 Unauthorized | Wrong password, or Apache stripping the Authorization header | Re-copy the password **with its spaces**; if it persists, add `SetEnvIf Authorization "(.*)" HTTP_AUTHORIZATION=$1` to .htaccess |
| 404 rest_no_route | REST API disabled by a security plugin, or permalinks set to Plain | Settings → Permalinks → Post name, save; whitelist the REST API in the security plugin |
| No Application Passwords section | Site on HTTP, or the feature disabled by a plugin | Move to HTTPS — required anyway |
| Upload failed, file type not permitted | WordPress blocks most types by default | PNG/JPG for images, ZIP for downloads; HTML stays blocked and should |
| Wrong author on the live post | `author` missing from the payload, defaulted to admin | Send the explicit ID on every create call |
| Password worked, then suddenly 401s | It was revoked, or the user's role changed | Generate a fresh one; the ten-second revoke cuts both ways |

Never retry a failing call blindly, and never skip the pre-flight to save a
second. Check the four in order — session validity (users/me), the User-Agent
header, quota on any research API, the image key — before blaming the pipeline.

## Rules

- **Pre-flight on every run**, because the users/me call is free and a broken
  password discovered after the work is written is money burned.
- **The spaces are part of the password**, because stripping them is the most
  common self-inflicted 401.
- **Explicit author ID on every create**, because defaulting to admin discards
  the credibility the content was built to earn.
- **Application password, never your real one**, because a ten-second revoke is
  the entire safety model.
- **A 403 is almost never your credentials** — it is the WAF and the User-Agent
  header, and knowing that saves an hour of password resets.

## Related skills

- **env-and-keys-setup** — where this password lives, with the other keys.
- **agent-folder-scaffold** — the .env this fills was created in step 5 there.
- **site-architecture** — what to publish once the pipe exists.
- **claude-md-writer** — the author ID becomes a hard rule in the driver.