API Explained: How Software Talks, Using Your WordPress Site

An API (application programming interface) is a published set of rules that lets one program ask another for data or actions without seeing its internals. The distinction that matters is between the interface and the implementation. The API is the menu of requests a system promises to honor. The code behind it can change completely, and your request still works. Every WordPress site since version 4.7 ships with one, so you already own an API whether you meant to or not.

TL;DR:

An API is a contract. It defines which requests a system accepts and what it sends back. It does not describe how the work gets done.

Most web APIs use HTTP. A method (GET, POST, PUT, DELETE) is sent to a URL called an endpoint, and the reply comes back as JSON with a status code.

WordPress has had a built-in REST API at /wp-json/ since version 4.7. Anyone can read public content through it, and writing requires authentication.

Application Passwords, added in WordPress 5.6, are the cleanest way to authenticate a script or tool without handing over your real login.

MCP (Model Context Protocol) is a standard way for AI assistants to discover and call APIs as "tools". It is how Claude or ChatGPT can edit a WordPress site on your behalf.

PRESSHAND

Put your WordPress API to work?

See how PressHand connects Claude or ChatGPT to all your WordPress sites so you can manage posts, SEO and plugins in plain English.

Visit →

API Explained Without the Waiter Analogy: Contract First, Code Second
What a Real API Request Looks Like, Line by Line
The Four Verbs and the Status Codes That Tell You What Happened
Authentication: How an API Knows the Request Is Yours
The WordPress REST API: What's Already Running on Your Site
Where MCP Fits: Giving AI Assistants a Way to Call APIs
When API Calls Fail, and How to Find the Real Cause
Manage Every WordPress Site You Own by Asking in Plain English
Frequently Asked Questions
Sources

API Explained Without the Waiter Analogy: Contract First, Code Second

Almost every API explainer uses a restaurant. The API is the waiter, the kitchen is the server, and you get your soup. That picture works until you need to debug something. A more useful mental model is a contract.

An API states three things in advance:

What you can ask for. These are the available operations, such as "list posts", "create a page" or "delete comment 42".
How to ask. This covers the exact address, the method, the required fields and the credentials.
What you'll get back. This covers the shape of the data and the codes that tell you whether it worked.

Everything behind that contract is the implementation, and the implementation is none of your business. A developer can rewrite the database layer, swap PHP versions or move hosts. A well-behaved API still answers the same request with the same shape of response. That stability is why APIs exist. Two pieces of software built by people who have never met can work together for years.

The contract also cuts the other way. If the API doesn't offer an operation, you can't do it through the API, however obviously the underlying system could. That limit catches people out more often than anything technical does.

What a Real API Request Looks Like, Line by Line

Here is a request you can send right now to almost any WordPress site. Paste it into a terminal, or put the URL in a browser:

curl https://example.com/wp-json/wp/v2/posts?per_page=2

That one line contains every part of a web API call:

The base URL (https://example.com/wp-json/). This is the root of the site's API.
The namespace and route (wp/v2/posts). This is the specific resource, in this case posts, from version 2 of the core WordPress API.
Query parameters (?per_page=2). These are options that adjust the request. Here they say "just two, please."
The method. It isn't written out because curl and browsers default to GET, which means "read."

The response comes back as JSON, a plain-text format of labeled fields. Trimmed down, it looks like this:

[
  {
    "id": 118,
    "date": "2024-05-02T09:14:00",
    "status": "publish",
    "title": { "rendered": "Spring opening hours" },
    "link": "https://example.com/spring-opening-hours/"
  }
]

Each post is an object with an id, which you'll use to refer to it later, plus its title, date and URL. The WordPress REST API Handbook documents every field and route. It is the most useful single reference if you plan to work with your site programmatically.

Pro Tip: Add ?_fields=id,title,link to any WordPress REST request and you get only those fields back. A default posts response includes rendered content, excerpts, link metadata and more. Trimming it can cut the payload by over 90% on content-heavy sites. That matters when a script loops through hundreds of posts. It matters even more when an AI assistant has to read the response and every unnecessary byte uses up its context.

The Four Verbs and the Status Codes That Tell You What Happened

Web APIs reuse the methods and status codes defined for HTTP itself. The core semantics are set out in the IETF's RFC 9110. Learn the handful below and you can read most API errors at a glance.

Method	What it means	WordPress example
GET	Read something	Fetch the last 10 posts
POST	Create something (WordPress also accepts it for updates)	Publish a new draft
PUT / PATCH	Update something that exists	Change post 118's title
DELETE	Remove something	Trash comment 42

Status code	Meaning	What to actually do
200 OK	It worked	Nothing
201 Created	It worked and made something new	Note the returned `id`
400 Bad Request	Your request was malformed	Check field names and data types
401 Unauthorized	It doesn't know who you are	Credentials missing or wrong
403 Forbidden	It knows who you are and says no	The user lacks that capability
404 Not Found	Wrong route or ID	Check the URL and the ID
429 Too Many Requests	You're being rate-limited	Slow down and retry later
500 Internal Server Error	The server broke	Check the PHP error log, not your request

MDN's HTTP status code reference covers the full list if you hit something rarer.

The split between 401 and 403 is the one worth memorizing. A 401 means "log in." A 403 means "logged in, still no." People burn hours regenerating passwords when the real problem is that the account is an Author trying to install a plugin.

401 means the API doesn't know who you are. 403 means it knows exactly who you are and the answer is still no.

Authentication: How an API Knows the Request Is Yours

Reading public posts needs no credentials, because that content is already on your public website. Writing anything, including drafts, edits, deletions and plugin changes, requires proof of identity. APIs handle this in a few common ways:

API keys. This is a long secret string sent with each request. It is simple, but it is usually all-or-nothing in what it allows.
OAuth tokens. You approve access through a login screen and the app gets a scoped, revocable token. It is common for large platforms and heavier to set up.
Application passwords. This is WordPress's built-in option, added in version 5.6. You generate a separate password per tool from your user profile, and you can revoke each one individually.

For a WordPress site, application passwords are what we'd pick nine times out of ten. They inherit the permissions of the user they belong to. If you create a dedicated Editor account for a tool, that tool can't touch plugins or users. If one leaks, you revoke that single password and nothing else breaks. By default, WordPress only offers them on sites served over HTTPS, which is the right call. The full setup, and the usual reasons they fail, are in our guide to WordPress Application Passwords.

Authentication is also where most real API security failures happen. The OWASP API Security Top 10 ranks broken object-level authorization first in its 2023 edition. That means an API correctly checks that you're logged in but fails to check whether this particular record is yours. WordPress's capability system handles this for core routes. Poorly written plugin endpoints sometimes don't, which is a good reason to keep your plugin list short.

The WordPress REST API: What's Already Running on Your Site

The REST API became part of WordPress core in version 4.7, released in December 2016. If your site is newer than that, and it is, the API is live. Visit yoursite.com/wp-json/ and you'll see a JSON index of every route your installation exposes, including ones added by plugins.

Out of the box, core routes cover:

Content. This includes posts, pages, media, revisions and custom post types that opt in.
Structure. This includes categories, tags, menus and menu items (menus were added to the REST API in WordPress 5.9).
People and feedback. This covers users and comments, with sensitive fields hidden from anonymous requests.
Site management. This covers plugins, themes and settings, all restricted to administrators.

SEO plugins typically register their own routes or store data in post meta. That's why tools that work with them need to know each plugin's conventions specifically. Calling the posts endpoint alone isn't enough.

Two practical consequences follow. First, a lot of "headless" and mobile tooling already relies on this API, so disabling it wholesale (some security plugins offer a switch) breaks more than you'd expect. Second, anything that can make authenticated HTTP requests can manage your site. That includes a shell script, a spreadsheet macro or an AI assistant.

Since WordPress 4.7, every install has shipped a REST API at /wp-json/. If your site exists, so does its API.

Where MCP Fits: Giving AI Assistants a Way to Call APIs

An AI chat assistant can't, on its own, send HTTP requests to your website. It needs a bridge that tells it which actions exist, what inputs each needs, and what came back. That bridge is what the Model Context Protocol standardizes. Anthropic released MCP as an open standard in November 2024.

The structure looks like this:

The MCP host. This is the AI app you're typing into.
The MCP server. This is a small program that wraps an API and describes its operations as named "tools", such as create_post or update_menu_item, each with a typed list of inputs.
The underlying API. In this case it's your WordPress REST API, which the server calls using your application password.

When you write "move the contact page to the end of the main menu," the assistant reads the tool list, picks the right tool, fills in the inputs and sends the call. The server then makes the actual REST request. Status codes and JSON come back, and the assistant turns them into a sentence. So MCP doesn't replace APIs. It's a contract for describing APIs to a model, sitting on top of the contract you just learned.

The practical upshot is that everything above still applies. If an action fails, the cause is almost always one of three things: a permission (403), a missing route (404) or a blocked request. Whether Claude or ChatGPT handles these calls more reliably is its own question. We compare them in ChatGPT vs Claude for Running a WordPress Site.

When API Calls Fail, and How to Find the Real Cause

Most failures on WordPress sites come from a short, boring list:

A security plugin or firewall blocks /wp-json/. Requests return 401, 403 or an HTML page instead of JSON. Allowlist the routes you need rather than turning protection off.
The host strips the Authorization header. Some Apache and CGI setups drop it silently, so a correct password still gets a 401. A one-line .htaccess rule usually fixes it, and your host can confirm which one.
Pretty permalinks are off. /wp-json/ returns 404. The fallback ?rest_route=/wp/v2/posts still works, and turning permalinks on fixes it properly.
The user role is too low. Authors can't edit others' posts, and only administrators manage plugins. This is a 403, and the fix is a role change, not a new password.
A plugin throws a PHP error mid-request. You get a 500. The API is fine, and the plugin isn't.

When in doubt, run the same request with curl from your own machine. If it fails there too, the problem is the site, not whatever tool you're using.

Manage Every WordPress Site You Own by Asking in Plain English

Everything above describes the plumbing that Presshand uses. It runs on your own machine or server and connects Claude or ChatGPT to your sites' REST APIs through application passwords. That gives the assistant 83 WordPress jobs it can do on request: posts, pages, images, menus, plugins, CSS and comments. It also scores live pages for SEO out of 100, working with Yoast, Rank Math, All in One SEO and SEOPress. The licence is $97 once and covers every site you own. The Agency licence is $197 and adds rebrand and resell rights, so you can hand it to clients under your name. Both include three months of ReplaStats analytics plus its WordPress plugin, which you keep.

The honest limits: you still need your own Claude or ChatGPT account. Every failure mode in the previous section still applies, so a firewall blocking /wp-json/ blocks us too. Updates are included for 12 months, then optional at $49 a year. Check your host's REST API settings before buying.

Frequently Asked Questions

What does API stand for, and what does it actually do?

API stands for application programming interface. It is a defined set of requests one program can send to another, along with the responses it will get back. It lets software share data and trigger actions without either side needing to know how the other is built.

Is the WordPress REST API safe to leave enabled?

Yes, for most sites. Public routes only expose content that is already visible on your website, and every write action requires an authenticated user with the right capability. Disabling it entirely tends to break the block editor and many plugins, so restrict specific routes rather than switching the whole thing off.

What is the difference between an API and MCP?

An API is the interface a system exposes, such as WordPress's REST routes for posts and menus. MCP (Model Context Protocol) is a standard for describing those operations to an AI assistant as named tools, so the assistant can choose and call them. MCP sits on top of APIs rather than replacing them.

Why does my WordPress API request return 401 when my password is correct?

The most common cause is a server configuration that strips the Authorization header before WordPress sees it, so the request arrives without credentials. Security plugins that block /wp-json/ and using your main login password instead of an application password are the other usual culprits. Testing the same request with curl helps you narrow it down.

Do I need to know how to code to use an API?

You don't need to code to read from one. Pasting a WordPress /wp-json/ URL into a browser shows you live JSON. For writing data, tools such as curl, automation platforms or an AI assistant connected through MCP can make the requests for you. Understanding methods and status codes is enough to diagnose most problems.