openapi: 3.0.3 info: title: Yoast REST 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 - name: Posts description: WordPress post SEO metadata via WP REST API - name: Pages description: WordPress page SEO metadata via WP REST API 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' /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 /wp/v2/pages: get: operationId: listPagesWithSeo summary: List Pages With SEO Data description: >- Returns WordPress pages with Yoast SEO metadata appended. Each page includes yoast_head and yoast_head_json fields. tags: - Pages parameters: - name: slug in: query required: false description: Filter by page 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 pages per page (max 100) schema: type: integer default: 10 maximum: 100 responses: '200': description: List of pages with SEO metadata content: application/json: schema: type: array items: $ref: '#/components/schemas/PageWithSeo' /wp/v2/pages/{id}: get: operationId: getPageWithSeo summary: Get Page With SEO Data description: >- Returns a single WordPress page with Yoast SEO metadata including yoast_head and yoast_head_json fields. tags: - Pages parameters: - name: id in: path required: true description: WordPress page ID schema: type: integer responses: '200': description: Page with SEO metadata content: application/json: schema: $ref: '#/components/schemas/PageWithSeo' '404': description: Page not found components: schemas: 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 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 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 yoast_head_json: $ref: '#/components/schemas/SeoMetadata' PageWithSeo: type: object description: WordPress page with Yoast SEO metadata properties: id: type: integer description: Page 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 link: type: string format: uri yoast_head: type: string description: HTML meta tags and Schema.org output for the yoast_head_json: $ref: '#/components/schemas/SeoMetadata' ErrorResponse: type: object properties: code: type: string message: type: string data: type: object properties: status: type: integer