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, 
        "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, 
        "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 Redirections

Since SEOPress 8.8, you can request your SEOPress’ redirections using our REST API.

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

1 route is currently available:

  • /wp-json/seopress/v1/redirections: to get all redirects, list of available arguments below:
    • id (optional): integer, redirect ID
    • enabled (optional): string, yes or no
    • type (optional): array of redirect types, 301, 302, 307, 404, 410, 451

Available method: GET.

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

{
  "success": true,
  "data": {
    "1681": {
      "origin": "my-origin-redirect",
      "destination": "https://www.seopress.org/redirect",
      "enabled": "yes",
      "type": "301",
      "param": "",
      "enabled_regex": "",
      "logged_status": "",
      "ip": "",
      "ua": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/136.0.0.0 Safari/537.36",
      "full_origin": "",
      "date_request": "",
      "count": "14",
      "redirect_date_request": "1747125367"
    }
  }
}

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
    • ignore (optional): boolean (1 or 0)
    • 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_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",
            "issue_ignore": "1"
        },
        {
            "id": "2",
            "post_id": "1",
            "issue_name": "keywords_permalink",
            "issue_desc": "",
            "issue_type": "permalink",
            "issue_priority": "medium",
            "issue_ignore": "0"
        },
        {
            "id": "3",
            "post_id": "1",
            "issue_name": "headings_h1_without_target_kw",
            "issue_desc": "",
            "issue_type": "headings",
            "issue_priority": "high",
            "issue_ignore": "0"
        }
    ];
}

Request Google Page Speed report

Since SEOPress 8.8, you can request your Google Page Speed report using our REST API.

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

1 route is currently available:

  • /wp-json/seopress/v1/page-speed to get the Google Page Speed report, list of available arguments below:
    • device (optional): mobile (default) or desktop

Available method: GET.

You will get a JSON response.

Request Google Analytics 4 stats

Since SEOPress 8.8, you can request your Google Analytics 4 stats using our REST API.

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

1 route is currently available:

  • /wp-json/seopress/v1/ga4 to get the Google Analytics 4 stats

Available method: GET.

You will get a JSON response with all the metrics per date.

Request Matomo Analytics stats

Since SEOPress 8.8, you can request your Matomo Analytics stats using our REST API.

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

1 route is currently available:

  • /wp-json/seopress/v1/matomo to get the Matomo Analytics stats

Available method: GET.

You will get a JSON response with all the metrics per date.

Request rankings from SEOPress Insights

Since SEOPress Insights 2.0, you can request your keyword rankings using our REST API.

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

1 route is currently available:

  • /wp-json/seopress-insights/v1/rankings, list of available arguments below:
    • kws (optional): array of IDs
    • cpt (optional): string, seopress_rankings
    • dates (optional): array of timestamp

Available method: GET.

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

{
    "2025/02/17": [
        {
            "keyword": "your keyword",
            "p": 18,
            "url": "https://www.seopress.org/example",
            "search_volume": 2900,
            "cpc": 4.1100000000000003,
            "competition": 0.13,
            "date": 1739760053,
            "added": 1634064757,
            "id": 7389
        }
    ],
}

Request competitors from SEOPress Insights

Since SEOPress Insights 2.0, you can request your competitors ranking on the first position using our REST API.

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

1 route is currently available:

  • /wp-json/seopress-insights/v1/competitors, list of available arguments below:
    • kws (optional): array of IDs
    • cpt (optional): string, seopress_p1_rankings
    • dates (optional): array of timestamp

Available method: GET.

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

{
    "2025/02/17": [
        {
            "keyword": "your keyword",
            "p": 18,
            "url": "https://www.example.com/my-competitor",
            "search_volume": 2900,
            "cpc": 4.1100000000000003,
            "competition": 0.13,
            "date": 1739760053,
            "added": 1634064757,
            "id": 7389
        }
    ],
}

Since SEOPress Insights 2.0, you can request your backlinks using our REST API.

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

1 route is currently available:

  • /wp-json/seopress-insights/v1/backlinks

Available method: GET.

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

[
    {
        "backlink": "https://example.com/seopress",
        "acr_rank": 1,
        "anchor_text": "visit website",
        "source_title": "SEOPress",
        "source_out_domains_ext": "2",
        "source_out_links_ext": "3",
        "source_out_links_int": "6",
        "source_language": "en",
        "source_language_desc": "English",
        "source_language_conf": 99,
        "flag_redirect": 0,
        "flag_frame": 0,
        "flag_no_follow": 1,
        "flag_images": 0,
        "flag_deleted": 0,
        "flag_alt_text": 0,
        "flag_mention": 0,
        "target_url": "https://www.seopress.org/",
        "indirect_target_url": "",
        "indirect_target_type": "",
        "target_title": "SEOPress - The Best SEO Tools for WordPress in 2025",
        "target_language": "en",
        "target_language_desc": "English",
        "target_language_conf": 99,
        "links_root_domain": -1,
        "domain_id": 3245,
        "first_indexed_date": "2025-02-19",
        "last_seen_date": "2025-02-19",
        "date_lost": "",
        "reason_lost": "",
        "link_type": "TextLink",
        "link_sub_type": "TextLink_Normal",
        "target_citation_flow": 42,
        "target_trust_flow": 28,
        "target_topical_tf": "Business",
        "target_topical_tf_value": 27,
        "source_cf": 9,
        "source_tf": 0,
        "source_topical_tf": "",
        "source_topical_tf_value": "",
        "source_topical_tf_1": "",
        "source_topical_tf_value_1": "",
        "source_topical_tf_2": "",
        "source_topical_tf_value_2": "",
        "date": false
    },
]