Hydrogen SEO
Log inStart free

The Plugin REST API

How the dashboard talks to WordPress, and how you can too.

5 min read
On this page
  1. Namespace and conventions
  2. Authentication
  3. Route groups
  4. Core settings
  5. Titles and meta
  6. Homepage, robots and llms.txt
  7. Sitemap
  8. Schema markup
  9. Metabox (the SEO Settings sheet)
  10. Analysis and site checks
  11. Redirections
  12. AI-backed endpoints
  13. Connection and agent
  14. Onboarding
  15. What is verified vs general guidance
  16. Related reading

Every screen in the Hydrogen SEO WordPress plugin — the dashboard, the SEO Settings sheet, the robots and llms.txt editors — is backed by the plugin's own REST API. Nothing in the admin UI can do anything the API cannot, which makes it a solid surface for scripting, CI checks and external tooling. This page documents the namespace, authentication model and the main route groups, as verified in the plugin source (Beta — routes may evolve between releases).

Namespace and conventions

All routes live under one namespace:

code
/wp-json/hydrogen-seo/v1/

The plugin registers routes through a shared base class, which gives every endpoint consistent behaviour:

  • Responses are standard JSON with success/data or error payloads.
  • Unless a route supplies its own permission callback, the default permission check requires the manage_options capability (the plugin defines this as its required capability constant).
  • Settings-style modules register a standard trio: GET /{base} to read, POST /{base} to update, and POST /{base}/reset to restore defaults. The robots editor, llms.txt editor, sitemap settings and similar modules all follow this pattern.

Modules can also add routes of their own via the hydrogen_seo_register_rest_routes action, which fires with the namespace string — see the Actions Reference for an example of registering your own endpoint alongside the plugin's.

Authentication

Two scenarios matter.

Inside wp-admin (the plugin's own apps). The React dashboard and metabox send a X-WP-Nonce header (created with wp_create_nonce( 'wp_rest' )) with every request, and the user's session cookie carries identity. The metabox endpoints explicitly verify both the nonce and the manage_options capability; most other endpoints verify the capability through the default permission callback. If you script against the API from a logged-in admin page, reuse the localized nonce.

External calls. For requests from outside WordPress (curl, CI, external services), use a WordPress application password over HTTPS with Basic authentication. This is the same mechanism Hydrogen AI uses: connecting the agent creates one application password named "Hydrogen SEO Agent", revocable at any time under Users → Profile → Application Passwords (see connect Hydrogen AI). The authenticated user must have manage_options for the plugin's routes to authorize.

php
// Example: read plugin settings from an external PHP script.
$response = wp_remote_get( 'https://example.com/wp-json/hydrogen-seo/v1/settings', [
    'headers' => [
        'Authorization' => 'Basic ' . base64_encode( 'admin:xxxx xxxx xxxx xxxx xxxx xxxx' ),
    ],
] );
$settings = json_decode( wp_remote_retrieve_body( $response ), true );

Or with curl:

code
curl -u "admin:xxxx xxxx xxxx xxxx xxxx xxxx" \
  https://example.com/wp-json/hydrogen-seo/v1/settings

Note: nothing here involves hydrogenseo.com API keys. Those authenticate the plugin to the SaaS for AI features and are managed separately — see API keys and licenses.

Route groups

The following groups were verified in the source. Placeholders like {post_id} are numeric; {context} is post or term.

Core settings

  • GET /settings — read all plugin settings.
  • POST /settings — update settings; expects a settings object in the body.
  • GET /variables — list supported template variables (the same list the smart-tags editor shows).

Titles and meta

  • GET|POST /titles-meta and POST /titles-meta/reset — module settings.
  • POST /titles-meta/preview — render a title/description template preview.

Homepage, robots and llms.txt

  • GET|POST /homepage-settings — homepage SEO settings.
  • GET|POST /robots-settings — site-wide robots meta settings.
  • GET|POST /robots-editor, POST /robots-editor/reset, GET /robots-editor/data — the robots.txt editor content and its supporting data.
  • GET|POST /llms-txt, POST /llms-txt/reset — the llms.txt editor content.

Sitemap

  • GET|POST /sitemap/settings, POST /sitemap/settings/reset — sitemap configuration.
  • POST /sitemap/cache/clear — clear the sitemap cache (fires the hydrogen_seo_sitemap_cache_cleared action).

Schema markup

  • GET /schema-markup/generate/{post_id} — generate the schema for a post.
  • GET /schema-markup/types and GET /schema-markup/types-info — available schema types.
  • GET|POST /schema-markup/settings and GET|POST /schema-markup/settings/{type} — global and per-type schema settings (admin capability enforced).
  • GET /schema-markup/variables, GET /schema-markup/fields/{type} — smart-tag variables and per-type field definitions.

Metabox (the SEO Settings sheet)

  • GET /metabox/{context}/{id} — read SEO data for a post or term.
  • POST /metabox/{context}/{id} — save SEO data; expects a data object. Firing point of the hydrogen_seo_metabox_post_data_saved / hydrogen_seo_metabox_term_data_saved actions.
  • POST /metabox/analyze — run content analysis; accepts content and an optional focus_keyword.
  • GET /metabox/schemas/{context}/{id} — schemas applicable to the entity.

These routes verify the REST nonce and capability together.

Analysis and site checks

  • POST /seo-analysis/analyze/{post_id} and GET /seo-analysis/results/{post_id} — run and read per-post analysis.
  • GET|POST /seo-analysis/settings — analysis settings.
  • GET /site-checks and POST /site-checks/refresh — the site-wide checks behind the site health score.

Redirections

  • GET /redirections — list redirects.
  • POST /redirection — create a redirect.
  • /redirection/{id} — update or delete a specific redirect.
  • /auto-redirection — the automatic-redirect option.

AI-backed endpoints

These proxy to hydrogenseo.com and require a connected account with credits: POST /ai/generate-content, POST /ai/generate-image, POST /ai/generate-alt-text, POST /metadata/generate, POST /metadata/bulk-generate, POST /content/generate, POST /content/expand, POST /content/improve, POST /featured-image/generate, POST /featured-image/upload, POST /image-alt/generate, POST /image-alt/bulk-generate, GET /image-alt/stats, POST /bulk-alt/process, plus embeddings routes (/embeddings/generate, /embeddings/search, /embeddings/bulk-generate).

Connection and agent

  • POST /connect/start, GET /connect/poll, GET /connect/status, POST /connect/lead, POST /connect/save-key, POST /connect/disconnect — the account connection flow (all require manage_options).
  • The Hydrogen AI agent has its own group: GET /agent/status, POST /agent/connect, POST /agent/disconnect, POST /agent/abilities, GET /agent/threads, DELETE /agent/threads/{thread}, POST /agent/threads/{thread}/message, POST /agent/threads/{thread}/resume, GET /agent/credits, GET /agent/settings, POST /agent/sync, GET /agent/tools, GET /agent/memories. Every agent route is gated by manage_options.

Onboarding

  • GET /onboarding/status and POST /onboarding — setup wizard state.

What is verified vs general guidance

Everything above — the namespace, the default manage_options permission model, the nonce checks on metabox routes, and the route paths — was read directly from the plugin source. Two things are general guidance rather than verified plugin behaviour: application passwords are core WordPress functionality (the plugin relies on it for the agent connection but does not reimplement it), and exact request/response body shapes are not exhaustively documented here because they are still settling during the Beta. When in doubt, the definitive contract is the source of the module that registers the route, or a quick GET against the endpoint with an admin credential.

Was this page helpful?
Still stuck? Contact support