Skip to content Skip to navigation
Back to the main support

Get started with the SEOPress REST API

Authentification methods

Using WordPress cookies

Headers to send with your request:

  • X-WP-Nonce: open your browser console, enter “wpApiSettings” and copy the nonce
  • Cookie: open your browser console, go to Applications, and copy the name AND the value of this cookie wordpress_logged_in_ (eg: wordpress_logged_in_41432erzre768dffez23456=admin%AREGREJOGRE54Y65KO534KTO4O3TJ43EFFEKZFOEZK£FEZRGTH)

Using Application passwords

SEOPress 6.8 is required.

This is the best solution. Create an application password from your WordPress profile.

Use your WP login (eg: admin) and this new app password to authenticate (choose “Basic Authentification” from Postman or equivalent).

Body (JSON Object) to sent with your request depending on the endpoint:

Title and meta description

{
    "title":"this is SEO title",
    "description":"this is meta description"
}

Target keywords

{
    "_seopress_analysis_target_kw":"keyword1, keyword2"
}

Social metadata

{
    "_seopress_social_fb_title":"my facebook title",
    "_seopress_social_fb_desc":"my facebook description",
    "_seopress_social_fb_img":"facebook image URL",
    "_seopress_social_fb_img_attachment_id":"facebook attachment ID",
    "_seopress_social_fb_img_width":"facebook attachment width",
    "_seopress_social_fb_img_height":"facebook attachment height",
    "_seopress_social_twitter_title":"my twitter title",
    "_seopress_social_twitter_desc":"my twitter description",
    "_seopress_social_twitter_img":"twitter image URL",
    "_seopress_social_twitter_img_attachment_id":"twitter attachment ID",
    "_seopress_social_twitter_img_width":"twitter attachment width",
    "_seopress_social_twitter_img_height":"twitter attachment height"
}

Meta robots

{
    "_seopress_robots_index":"yes",
    "_seopress_robots_follow":"yes",
    "_seopress_robots_archive":"yes",
    "_seopress_robots_snippet":"yes",
    "_seopress_robots_imageindex":"yes",
    "_seopress_robots_canonical":"my canonical URL",
    "_seopress_robots_primary_cat":"my primary cat ID",
    "_seopress_robots_breadcrumbs":"my custom breadcrumbs"
}

Redirection

{
    "_seopress_redirections_enabled":"yes",
    "_seopress_redirections_logged_status":"both|only_logged_in|only_not_logged_in",
    "_seopress_redirections_type":"301|302|307",
    "_seopress_redirections_value":"my redirection URL"
}

Response:

If success:

{
    "code": "success"
}

If fail:

{
    "code": "rest_forbidden",
    "message": "Sorry, you are not allowed to do that.",
    "data": {
        "status": 401
    }
}

or

{
    "code": "rest_cookie_invalid_nonce",
    "message": "Cookie check failed",
    "data": {
        "status": 403
    }
}

Request post metadata

Since SEOPress 5.0, you can request your post SEO metadata using our REST API.

Note that for security reasons, you must be logged in with a user having the edit_post capability.

2 routes are currently available:

  • /wp-json/seopress/v1/posts/[postId] : replace [postId] by the ID of your post
  • /wp-json/seopress/v1/posts/by-url?url=https://example.com/seopress-best-wordpress-seo-plugin/ replace the URL by the desired permalink

Available method: GET.

You will get in response a JSON with the following informations:

{ 
    "title": "SEOPress, Best WordPress SEO plugin", 
    "description": "My super meta description", 
    "canonical": "https://example.com/seopress-best-wordpress-seo-plugin/", 
    "og": { 
        "title": "My Facebook title", 
        "description": "My Facebook description", 
        "image": "https://example.com/seopress-best-wordpress-seo-plugin.jpg",
        "attachment_id": "1",
        "image_width": "1920",
        "image_height": "1080"
    }, 
    "twitter": { 
        "title": "My Twitter title", 
        "description": "My Twitter description", 
        "image": "https://example.com/seopress-best-wordpress-seo-plugin.jpg",
        "attachment_id": "1",
        "image_width": "1920",
        "image_height": "1080"
    },
    "robots": {
        "noindex": false, 
        "nofollow": false, 
        "noarchive": false, 
        "nosnippet": false, 
        "noimageindex": false 
    },
    "primarycat": "1",
    "breadcrumbs": "my custom breadcrumbs for current item",
    "redirections": {
        "enabled": true,
        "status":"both",
        "type":"301",
        "value":"https://example.com/destination-url/"
    }
}

To request your data, you can for example use the WordPress HTTP API.

Request term metadata

Since SEOPress 5.5, you can request your term SEO metadata using our REST API.

Note that for security reasons, you must be logged in with a user having the edit_post capability.

2 routes are currently available:

  • /wp-json/seopress/v1/terms/[termId] : replace [termId] by the ID of your term
  • /wp-json/seopress/v1/terms/[termId]?taxonomy=[yourCustomTaxonomy] similar to the previous route, with taxonomy argument (default: “category” if not provided)

Available method: GET.

You will get in response a JSON with the following informations:

{ 
    "title": "My super term title", 
    "description": "My super term meta description",
    "canonical": "https://example.com/seopress-best-wordpress-seo-plugin/",
    "og": { 
        "title": "My Facebook term title", 
        "description": "My Facebook term description", 
        "image": "https://example.com/term-seopress-best-wordpress-seo-plugin.jpg",
        "attachment_id": "1",
        "image_width": "1920",
        "image_height": "1080" 
    }, 
    "twitter": { 
        "title": "My Twitter term title", 
        "description": "My Twitter term description", 
        "image": "https://example.com/term-seopress-best-wordpress-seo-plugin.jpg",
        "attachment_id": "1",
        "image_width": "1920",
        "image_height": "1080"
    }, 
    "robots": { 
        "noindex": false, 
        "nofollow": false, 
        "noarchive": false, 
        "nosnippet": false, 
        "noimageindex": false 
    },
    "breadcrumbs": "my custom breadcrumbs for current item",
    "redirections": {
        "enabled": true,
        "status":"both",
        "type":"301",
        "value":"https://example.com/destination-url/"
    }
}

Send post metadata

To write SEO post metadata, you can use these endpoints:

  • title and meta description: /wp-json/seopress/v1/posts/[postId]/title-description-metas
  • target keywords: /wp-json/seopress/v1/posts/[postId]/target-keywords
  • social meta: /wp-json/seopress/v1/posts/[postId]/social-settings
  • meta robots: /wp-json/seopress/v1/posts/[postId]/meta-robot-settings
  • redirection: /wp-json/seopress/v1/posts/[postId]/redirection-settings

Required user capability for security: edit_post

Available method: PUT.

Request SEOPress’ settings

Since SEOPress 5.5, you can request your SEOPress’ global settings using our REST API.

Note that for security reasons, you must be logged in with a user having the manage_options capability.

10 routes are currently available:

  • /wp-json/seopress/v1/options/dashboard-settings: Dashboard settings
  • /wp-json/seopress/v1/options/titles-settings: Titles and metas settings
  • /wp-json/seopress/v1/options/social-settings: Social networks settings
  • /wp-json/seopress/v1/options/sitemaps-settings: Sitemaps settings
  • /wp-json/seopress/v1/options/analytics-settings: Analytics settings
  • /wp-json/seopress/v1/options/advanced-settings: Advanced settings
  • /wp-json/seopress/v1/options/bot-settings: Bot settings
  • /wp-json/seopress/v1/options/indexing-settings: Instant Indexing settings
  • /wp-json/seopress/v1/options/license-settings: License settings
  • /wp-json/seopress/v1/options/pro-settings: PRO settings

Available method: GET.

You will get in response a JSON with the following informations (eg. with Dashboard settings):

{
  "cards_order": [
    "seopress-page-list",
    "notice-insights-alert",
    "seopress-news-panel"
  ],
  "toggle-rich-snippets": "1",
  "toggle-404": "1",
  "toggle-bot": "1",
  "toggle-titles": "1",
  "toggle-white-label": "0",
  "toggle-social": "1",
  "toggle-xml-sitemap": "1",
  "toggle-google-analytics": "1",
  "toggle-advanced": "1",
  "toggle-woocommerce": "1",
  "toggle-edd": "1",
  "toggle-local-business": "1",
  "toggle-dublin-core": "1",
  "toggle-breadcrumbs": "1",
  "toggle-robots": "1",
  "toggle-news": "1",
  "toggle-rewrite": "1",
  "toggle-instant-indexing": "1",
  "notice-wizard": "1"
}

Request Search Console reports of your posts

Since SEOPress 5.7, you can request your Google Search Console reports of your posts using our REST API.

Note that for security reasons, you must be logged in with a user having the edit_post capability.

1 route is currently available:

  • /wp-json/seopress/v1/posts/[postID]/inspect : replace [postID] by the ID of your post

Available method: GET, POST.

You will get in response a JSON with the following informations:

{
    "google_api_key_is_empty": false,
    "data": {
        "inspectionResult": {
            "inspectionResultLink": "https://search.google.com/search-console/inspect?resource_id=https://example.com/&id=xxxxxxxx&utm_medium=link&utm_source=api",
            "indexStatusResult": {
                "coverageState": "Indexed, not submitted in sitemap",
                "crawledAs": "MOBILE",
                "googleCanonical": "https://example.com/",
                "indexingState": "INDEXING_ALLOWED",
                "lastCrawlTime": "2022-04-29T13:25:27Z",
                "pageFetchState": "SUCCESSFUL",
                "referringUrls": [
                    "https://www.example.com/"
                ],
                "robotsTxtState": "ALLOWED",
                "sitemap": null,
                "userCanonical": "https://example.com/",
                "verdict": "PASS"
            },
            "mobileUsabilityResult": {
                "verdict": "PASS"
            },
            "richResultsResult": {
                "verdict": "PASS",
                "detectedItems": [
                {
                    "richResultType": "Logos",
                    "items": [
                    {
                        "name": "Unnamed item"
                    }
                    ]
                },
                {
                    "richResultType": "Sitelinks searchbox",
                    "items": [
                        {
                            "name": "Unnamed item"
                        }
                        ]
                    }
                ]
            }
        }
    }
}

Request SEO issues

Since SEOPress 8.2, you can request your SEO issues (Site Audit feature) using our REST API.

Note that for security reasons, you must be logged in with a user having the manage_options capability.

2 routes are currently available:

  • /wp-json/seopress/v1/seo-issues/[postId] : to get the SEO issues of the post, replace [postId] by the desired post ID
  • /wp-json/seopress/v1/seo-issues/ to get all issues, list of available arguments below:
    • id (optional): post ID
    • type (optional): all_canonical, json_schemas, old_post, permalink, headings, title, description, social, robots, img_alt, nofollow_links, outbound_links, internal_links
    • priority (optional): high, medium, low, good
    • name (optional): json_schemas_duplicated, json_schemas_not_found, old_post, keywords_permalink, headings_not_found, headings_h1_duplicated, headings_h1_not_found, headings_h1_without_target_kw, headings_h2_without_target_kw, headings_h3_without_target_kw, title_without_target_kw, title_too_long, title_not_custom, description_without_target_kw, description_too_long, description_not_custom, og_title_duplicated, og_title_empty, og_title_missing, og_desc_duplicated, og_desc_empty, og_desc_missing, og_img_empty, og_img_missing, og_url_duplicated, og_url_empty, og_url_missing, og_sitename_duplicated, og_sitename_empty, og_sitename_missing, x_title_duplicated, x_title_empty, x_title_missing, x_desc_duplicated, x_desc_empty, x_desc_missing, x_img_empty, x_img_missing, meta_robots_duplicated, meta_robots_noindex, meta_robots_nofollow, meta_robots_noimageindex, meta_robots_noarchive, meta_robots_nosnippet, meta_robots_nositelinkssearchbox, img_alt_missing, img_alt_no_media, nofollow_links_too_many, outbound_links_missing, internal_links_missing, canonical_duplicated, canonical_missing

Available method: GET.

You will get in response a JSON with the following informations:

{
    "success": true,
    "data": [
        {
            "id": "1",
            "post_id": "1",
            "issue_name": "json_schemas_not_found",
            "issue_desc": "",
            "issue_type": "json_schemas",
            "issue_priority": "medium"
        },
        {
            "id": "2",
            "post_id": "1",
            "issue_name": "keywords_permalink",
            "issue_desc": "",
            "issue_type": "permalink",
            "issue_priority": "medium"
        },
        {
            "id": "3",
            "post_id": "1",
            "issue_name": "headings_h1_without_target_kw",
            "issue_desc": "",
            "issue_type": "headings",
            "issue_priority": "high"
        }
    ];
}