OpenAPI Specification
openapi: 3.0.3
info:
title: Yoast REST Pages SEO Head 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: SEO Head
description: Retrieve SEO metadata for any URL
paths:
/yoast/v1/get_head:
get:
operationId: getSeoHead
summary: Get SEO Head for URL
description: Returns all SEO metadata for a given URL including meta tags, Schema.org JSON-LD structured data, canonical URL, robots directives, Open Graph tags, and Twitter Card data. This is the primary endpoint for headless WordPress implementations.
tags:
- SEO Head
parameters:
- name: url
in: query
required: true
description: The full URL of the page to retrieve SEO metadata for
schema:
type: string
format: uri
example: https://example.com/blog/my-post/
responses:
'200':
description: SEO metadata for the requested URL
content:
application/json:
schema:
$ref: '#/components/schemas/SeoHeadResponse'
'404':
description: URL not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
components:
schemas:
ErrorResponse:
type: object
properties:
code:
type: string
message:
type: string
data:
type: object
properties:
status:
type: integer
SeoHeadResponse:
type: object
description: SEO metadata response for a URL
properties:
html:
type: string
description: Escaped prefabricated meta tags and Schema.org JSON-LD markup for the <head>
json:
$ref: '#/components/schemas/SeoMetadata'
status:
type: integer
description: HTTP status code for the requested URL
example: 200
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