skip to content →
FIELD_MANUAL / LIVEREVISIONv1.2 · 2026.04.13CHAPTERS4 FILEDCH_05INTEGRATION
[ CH_05 / FIELD_MANUAL ]API · MONITORING · CMS_ADAPTERS

The field manual.
wire it in, read the signals.

Everything you need to integrate VectraSEO with your stack — REST API reference, site monitoring rules, eight CMS adapters, and the custom-API payload spec.

CH_05.01REST API reference→CH_05.02Site monitoring→CH_05.03CMS adapters→CH_05.04Custom API→
[ CH_05.01 / REST_API ]

REST API reference

All endpoints live under /api/v1. Authentication uses Authorization: Bearer <jwt> obtained via magic link login. Tokens rotate hourly; refresh via the auth endpoint when yours expires.

> base_url
https://api.vectraseo.com/api/v1
Authentication
POST/auth/magic-linkRequest magic link
POST/auth/magic-link/verifyVerify token, get JWT
Projects
GET/projectsList projects
POST/projectsCreate project
GET/projects/:idGet project
PUT/projects/:idUpdate project
DELETE/projects/:idDelete project
POST/projects/:id/runTrigger pipeline run
Competitors
GET/projects/:id/competitorsList competitors
POST/projects/:id/competitorsAdd competitor
DELETE/projects/:id/competitors/:cidRemove competitor
POST/projects/:id/competitors/analyzeRun analysis
Content Gaps
GET/projects/:id/gaps?limit=20&cursor=List gaps (paginated)
POST/projects/:id/gaps/identifyIdentify gaps
DELETE/projects/:id/gaps/:gap_idDelete gap
Blog Posts
GET/projects/:id/posts?limit=20&cursor=List posts (paginated)
POST/projects/:id/posts/generateGenerate posts
GET/projects/:id/posts/:post_idGet post
PUT/projects/:id/posts/:post_idUpdate post
DELETE/projects/:id/posts/:post_idDelete post
POST/projects/:id/posts/:post_id/publishPublish to CMS
Blog Publish (Inbound)
POST/blog/publishCreate blog post
PUT/blog/publish/:idUpdate blog post
DELETE/blog/publish/:idDelete blog post
Scheduler
GET/projects/:id/scheduleGet schedule
PUT/projects/:id/scheduleUpdate schedule
DELETE/projects/:id/scheduleDisable schedule
Monitors
GET/projects/:id/monitorsList monitors
POST/projects/:id/monitorsCreate monitor
GET/projects/:id/monitors/:midGet monitor
PUT/projects/:id/monitors/:midUpdate monitor
DELETE/projects/:id/monitors/:midDelete monitor
POST/projects/:id/monitors/:mid/scanTrigger manual scan
GET/projects/:id/monitors/:mid/scansList scan history
GET/projects/:id/monitors/:mid/issuesList active issues
Jobs
GET/jobs/:job_idPoll job status
GET/projects/:id/jobsList project jobs
[ CH_05.02 / SITE_MONITORING ]

Continuous SEO health checks

Monitors crawl your sitemap on a schedule (or on demand), run eleven health rules against every URL, and roll results up into a 0–100 health score. When new critical or warning issues land on a scan, VectraSEO emails your configured recipients.

Creating a monitor

  1. 01Open your project and go to Monitors → New Monitor.
  2. 02Enter your sitemap URL (e.g. https://yoursite.com/sitemap.xml). If you only have a root URL, VectraSEO will try common sitemap locations.
  3. 03Pick a schedule: daily or weekly. An hourly EventBridge rule enqueues due monitors automatically.
  4. 04Optionally add email recipients for issue alerts — fires when new critical or warning issues appear on a scan.
  5. 05Hit Run Scan to kick off the first crawl manually. Scans cover up to 200 URLs and usually complete in 1–3 minutes.

The twelve rules

RULE_ID
SEVERITY
CHECKS
broken_status
CRITICAL
Flags any URL returning a 4xx or 5xx HTTP status code.
redirect_chain
WARNING
Flags URLs that redirect more than twice before hitting a final 200.
missing_meta
WARNING
Flags pages missing a meta description, or where descriptions are duplicated across URLs.
og_twitter_tags
WARNING
Flags pages missing the Open Graph or Twitter Card meta tags used by social platforms to render link previews.
heading_structure
WARNING
Flags pages with zero or more than one <h1> heading — the SEO convention is exactly one primary heading per page.
viewport_meta
WARNING
Flags pages missing <meta name="viewport">, which mobile browsers require to render at device width.
image_alt
INFO
Flags <img> elements shipped without an alt attribute (empty alt="" on decorative images is accepted).
noindex_in_sitemap
WARNING
Flags pages listed in the sitemap but marked noindex — a conflicting signal for crawlers.
mixed_content
WARNING
Flags HTTPS pages that load scripts, images, or stylesheets over HTTP.
slow_response
INFO
Flags pages where time-to-first-byte exceeds 3 seconds.
spa_placeholder
CRITICAL
Flags SPA routes that return placeholder HTML without the real content — bots see an empty page.

Health score formula

The score starts at 100 and decays as issues pile up. Weights are tuned so a handful of criticals tank the score faster than a long tail of info noise.

formula.txt
score = max(0, 100 − (critical × 15) − (warning × 5) − (info × 1))
[ EXAMPLE_A ]
2·crit + 5·warn + 12·info
=
33
[ EXAMPLE_B ]
0·crit + 2·warn + 3·info
=
87
[ EXAMPLE_C ]
0·crit + 0·warn + 0·info
=
100

Issue response shape

Individual issues from /monitors/:mid/issues include the rule ID, severity, URL, a short message, a recommendation, and optional technical evidence.

issue.json
{
  "id": "iss_01H...",
  "monitor_id": "mon_01H...",
  "scan_id": "scan_01H...",
  "rule": "broken_status",
  "severity": "critical",
  "url": "https://yoursite.com/products/legacy",
  "message": "Returned 404 Not Found",
  "recommendation": "Either restore the page or add a 301 redirect to the replacement URL.",
  "evidence": {
    "status_code": 404,
    "response_time_ms": 182,
    "final_url": "https://yoursite.com/products/legacy"
  },
  "first_seen_at": "2026-04-12T09:14:22Z",
  "last_seen_at": "2026-04-13T09:14:22Z"
}
[ CH_05.03 / CMS_ADAPTERS ]

Supported CMS platforms

VectraSEO publishes directly to seven platforms plus Zapier for the long tail. Configure your CMS type and credentials in project settings.

ADAPTER_01
WordPress
<wordpress>

Publishes via the WordPress REST API. Featured images are uploaded to your WordPress media library automatically and attached to the post.

[ CREDENTIALS ]
site_urlusernameapp_password
[ SETUP ]
  1. 01Go to your WordPress admin → Users → Profile → Application Passwords.
  2. 02Enter a name (e.g. "VectraSEO") and click Add New Application Password.
  3. 03Copy the generated password — it will only be shown once.
  4. 04In VectraSEO project settings, enter your site_url, username, and the application password.
Requires WordPress 5.6+ with Application Passwords enabled. Self-hosted WordPress must have HTTPS and the REST API accessible at /wp-json/wp/v2.
ADAPTER_02
Wix
<wix>

Uses the Wix Headless CMS API. VectraSEO creates a draft post and automatically publishes it in a single flow.

[ CREDENTIALS ]
api_keysite_id
[ SETUP ]
  1. 01In your Wix dashboard, go to Settings → API Keys and create a new key with Blog permissions.
  2. 02Copy your API Key and Site ID (found in Settings → General under "Site ID").
  3. 03Paste both values into VectraSEO project settings.
The API key needs Blog → Posts read/write permissions. Wix handles slug generation from the post title.
ADAPTER_03
Shopify
<shopify>

Publishes to your Shopify store's blog via the Admin API. Featured images are embedded directly in the HTML body as CloudFront-hosted image tags.

[ CREDENTIALS ]
shop_domainaccess_tokenblog_id
[ SETUP ]
  1. 01In your Shopify admin, go to Apps → Develop apps and create a new app.
  2. 02Under API access scopes, enable write_content.
  3. 03Install the app and copy the Admin API access token.
  4. 04Find your Blog ID: go to Online Store → Blog posts, click your blog, and copy the numeric ID from the URL.
  5. 05Enter shop_domain, access token, and blog ID in project settings.
Shopify blog articles don't support a separate featured image field via the REST API, so images are prepended to the HTML body.
ADAPTER_04
Squarespace
<squarespace>

Publishes directly to a Squarespace blog collection via the Squarespace API. Posts are published immediately (not as drafts).

[ CREDENTIALS ]
api_keysite_idcollection_id
[ SETUP ]
  1. 01In your Squarespace site, go to Settings → Developer API Keys and generate a new API key.
  2. 02Find your Site ID in Settings → General.
  3. 03Find your Collection ID: go to Pages, click your blog page, and note the ID.
  4. 04Enter all three values in VectraSEO project settings.
Requires a Squarespace Business plan or higher for API access. The API key needs content management permissions.
ADAPTER_05
Blogger
<blogger>

Publishes via the Google Blogger API v3. Posts are published immediately with tags applied as labels. Featured images are embedded in the HTML body.

[ CREDENTIALS ]
api_keyblog_id
[ SETUP ]
  1. 01Go to the Google Cloud Console and enable the Blogger API v3.
  2. 02Create an API Key under Credentials (restrict it to the Blogger API for security).
  3. 03Find your Blog ID: open your Blogger dashboard, go to Settings, and copy the numeric blog ID from the URL.
  4. 04Enter the API key and blog ID in VectraSEO project settings.
The API key must have Blogger API v3 enabled in Google Cloud Console. Posts are published as the blog owner.
ADAPTER_06
Zapier
<zapier>

Sends post data to a Zapier webhook, letting you route content to any of Zapier's 6,000+ app integrations. Payloads include an action field (publish, update, or delete) plus full post data.

[ CREDENTIALS ]
webhook_url
[ SETUP ]
  1. 01In Zapier, create a new Zap and choose Webhooks by Zapier as the trigger.
  2. 02Select Catch Hook and copy the generated webhook URL.
  3. 03Paste the webhook URL into VectraSEO project settings.
  4. 04Set up your Zap's action steps (e.g. post to Ghost, Notion, email, Slack).
  5. 05Test by publishing a post from VectraSEO — the payload will appear in Zapier for mapping.
The webhook receives full post data including title, body_html, slug, tags, images (CloudFront URLs), and project context. Use the action field to distinguish between publish, update, and delete events.
ADAPTER_07
Custom API
<custom_api>

Publishes to any REST endpoint. Configurable authentication, path, and retry logic with exponential backoff on server errors.

[ CREDENTIALS ]
endpoint_urlapi_key
[ SETUP ]
  1. 01Ensure your target API accepts POST requests with a JSON body (see payload format below).
  2. 02Enter your endpoint_url (base URL, no trailing slash) and api_key in project settings.
  3. 03Optionally set auth_header (defaults to Authorization: Bearer) and publish_path (defaults to /posts).
  4. 04Your API should return JSON with id and url fields.
VectraSEO retries up to 3 times with exponential backoff (2s, 4s, 8s) on 5xx errors. 4xx errors fail immediately. Images are sent as base64-encoded data. Requests use HTTP/2 with a 120-second timeout.
[ CH_05.04 / CUSTOM_API ]

Publishing to any endpoint

The Custom API adapter lets you ship posts to any REST endpoint. VectraSEO POSTs JSON with the following payload shape:

POST /posts — payload.json
{
  "title": "Post Title",
  "body_html": "<p>Full HTML content...</p>",
  "slug": "post-title",
  "tags": ["seo", "blogging"],
  "excerpt": "Meta description",
  "author": "Author Name",
  "images": [
    {
      "filename": "image.png",
      "data": "<base64-encoded>",
      "alt": "Alt text"
    }
  ],
  "published_at": "2026-04-05T00:00:00Z",
  "status": "published"
}

Configuration fields

FIELD
REQ
DESCRIPTION
endpoint_url
YES
Base URL of the target API (e.g. https://api.mysite.com)
api_key
YES
Authentication key sent with each request
auth_header
opt
Header name for API key. Default: Authorization (Bearer prefix).
publish_path
opt
POST path appended to base URL. Default: /posts
[ END_OF_MANUAL ]
[ NEED_HELP? ]

Can't find what
you're looking for?

Reach out to the team. We answer every email and we read every bug report.

contact_operator → or email support@vectraseo.com