OpenAPI Specification
openapi: 3.0.3
info:
title: Yoast REST Pages Posts API
description: The Yoast REST API returns all SEO metadata (meta tags, Schema.org JSON-LD, canonical URLs, Open Graph, Twitter Card data, and robots directives) for any URL or post on a WordPress site. The API is read-only and designed for headless WordPress implementations. It extends the WordPress WP-JSON REST API and provides a dedicated SEO head endpoint.
version: 1.0.0
contact:
name: Yoast Developer Portal
url: https://developer.yoast.com/
license:
name: GPL-3.0
url: https://www.gnu.org/licenses/gpl-3.0.html
x-logo:
url: https://yoast.com/app/uploads/2020/12/yoast-logo-new.svg
servers:
- url: https://{site}/wp-json
variables:
site:
default: example.com
description: Your WordPress site domain
tags:
- name: Posts
description: WordPress post SEO metadata via WP REST API
paths:
/wp/v2/posts:
get:
operationId: listPostsWithSeo
summary: List Posts With SEO Data
description: Returns WordPress posts with Yoast SEO metadata appended. Each post in the response includes yoast_head (HTML meta tags and Schema.org output) and yoast_head_json (structured key/value SEO data).
tags:
- Posts
parameters:
- name: slug
in: query
required: false
description: Filter by post slug
schema:
type: string
- name: page
in: query
required: false
description: Page number for pagination
schema:
type: integer
default: 1
- name: per_page
in: query
required: false
description: Number of posts per page (max 100)
schema:
type: integer
default: 10
maximum: 100
responses:
'200':
description: List of posts with SEO metadata
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/PostWithSeo'
/wp/v2/posts/{id}:
get:
operationId: getPostWithSeo
summary: Get Post With SEO Data
description: Returns a single WordPress post with Yoast SEO metadata including yoast_head (HTML output) and yoast_head_json (structured SEO data object).
tags:
- Posts
parameters:
- name: id
in: path
required: true
description: WordPress post ID
schema:
type: integer
responses:
'200':
description: Post with SEO metadata
content:
application/json:
schema:
$ref: '#/components/schemas/PostWithSeo'
'404':
description: Post not found
components:
schemas:
PostWithSeo:
type: object
description: WordPress post with Yoast SEO metadata
properties:
id:
type: integer
description: Post ID
date:
type: string
format: date-time
modified:
type: string
format: date-time
slug:
type: string
status:
type: string
title:
type: object
properties:
rendered:
type: string
content:
type: object
properties:
rendered:
type: string
excerpt:
type: object
properties:
rendered:
type: string
link:
type: string
format: uri
yoast_head:
type: string
description: HTML meta tags and Schema.org output for the <head>
yoast_head_json:
$ref: '#/components/schemas/SeoMetadata'
SeoMetadata:
type: object
description: Structured SEO metadata for a URL
properties:
title:
type: string
description: SEO page title
description:
type: string
description: Meta description
canonical:
type: string
format: uri
description: Canonical URL
robots:
type: object
description: Robots directives
properties:
index:
type: string
enum:
- index
- noindex
follow:
type: string
enum:
- follow
- nofollow
max-snippet:
type: string
max-image-preview:
type: string
max-video-preview:
type: string
og_locale:
type: string
description: Open Graph locale
og_type:
type: string
description: Open Graph type (e.g. article, website)
og_title:
type: string
description: Open Graph title
og_description:
type: string
description: Open Graph description
og_url:
type: string
format: uri
description: Open Graph URL
og_site_name:
type: string
description: Open Graph site name
og_image:
type: array
items:
type: object
properties:
url:
type: string
format: uri
width:
type: integer
height:
type: integer
type:
type: string
twitter_card:
type: string
description: Twitter Card type
twitter_title:
type: string
description: Twitter Card title
twitter_description:
type: string
description: Twitter Card description
twitter_image:
type: string
format: uri
description: Twitter Card image URL
article_published_time:
type: string
format: date-time
description: Article published time (ISO 8601)
article_modified_time:
type: string
format: date-time
description: Article last modified time (ISO 8601)
author:
type: string
description: Article author name
schema:
type: object
description: Schema.org JSON-LD structured data