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

REST API reference

All endpoints live under /api/v1. Two auth modes: interactive/management endpoints use a session JWT (Authorization: Bearer <jwt>) from magic-link login, while the read-only Analytics API (/projects/{id}/analytics/*) and the agent recommendations feed authenticate with a per-project API key sent as the x-api-key header — generate one under Project → Settings → Analytics API. Analytics calls are metered per project and return X-RateLimit-* headers.

To create and manage projects programmatically, use an account API key (vsak_) with the Provisioning API — it spans every project you own and carries explicit write scopes. The per-project vsk_ key stays read-only and is minted from a project that already exists, so it can neither create one nor reach a second.

Analytics API · response shapes

Each /analytics/* response below is the exact shape the live API returns. Three conventions trip up first-time integrators:

• AEO readiness lives inside health. The overview reports it as health.aeo_score — there is no top-level aeo object.
• Surfaces can be null. In /overview, each of health, visibility, search, traffic, and ranks is null until that source is connected and has data — normalize defensively.
• List endpoints are not cursor-paginated. They return { items, count } (visibility results return a bare array); there is no next_cursor/total and no server-side severity/category filters.

{
  "project_id": "prj_8fa21c",
  "period_days": 28,
  "health":     { "health_score": 92, "aeo_score": 78, "urls_checked": 184,
                  "critical": 0, "warning": 3, "info": 9 },
  "visibility": { "visibility_score": 61, "citation_rate": 0.34, "share_of_voice": 0.22 },
  "search":     { "clicks": 12431, "clicks_prev": 11705, "impressions": 402118,
                  "ctr": 0.031, "position": 14.2 },
  "traffic":    { "sessions": 18904, "engaged_sessions": 12880,
                  "key_events": 311, "revenue": 4820.50, "ai_referrals": 842 },
  "ranks":      { "tracked": 48, "top_10": 12, "wins_this_week": 3 },
  "generated_at": "2026-05-29T14:02:11Z"
}

{
  "connected": true,
  "property_url": "https://acme.com/",
  "period_days": 28,
  "clicks": 12431, "impressions": 402118, "ctr": 0.031, "position": 14.2,
  "clicks_prev": 11705, "impressions_prev": 389220, "ctr_prev": 0.030, "position_prev": 15.1,
  "daily": [
    { "date": "2026-05-01", "clicks": 402, "impressions": 13200, "ctr": 0.030, "position": 14.8 }
  ]
}

{
  "items": [
    { "query": "ai seo audit tool", "clicks": 312, "impressions": 8400, "ctr": 0.037, "position": 6.1 }
  ],
  "count": 25
}

{
  "items": [
    {
      "kind": "post", "target_id": "post_4f2a",
      "url": "https://acme.com/blog/aeo-guide", "title": "The AEO Guide",
      "clicks": 312, "impressions": 8400, "ctr": 0.037, "position": 6.1,
      "clicks_prev": 280, "impressions_prev": 8010, "ctr_prev": 0.035, "position_prev": 7.2,
      "clicks_delta": 32, "position_delta": 1.1
    }
  ],
  "count": 50
}

{
  "connected": true,
  "property_url": "https://acme.com/",
  "buckets": [
    { "bucket": "indexed", "severity": "info", "count": 184, "sparkline": [180,181,184], "examples": [] },
    { "bucket": "crawled_not_indexed", "severity": "warning", "count": 12, "sparkline": [10,11,12], "examples": [] },
    { "bucket": "excluded_noindex", "severity": "warning", "count": 31, "sparkline": [31,31,31], "examples": [] }
  ],
  "total_inspected": 227,
  "rollup_days": 30,
  "quota": { "used_today": 14, "daily_cap": 2000 },
  "last_synced_at": "2026-05-29T06:00:00Z"
}

{
  "items": [
    {
      "target_id": "post_4f2a",
      "url": "https://acme.com/blog/aeo-guide", "path": "/blog/aeo-guide",
      "matched": true,
      "sessions": 2104, "engaged_sessions": 1502, "engagement_rate": 0.714,
      "key_events": 41, "revenue": 980.00,
      "sessions_prev": 1788, "engaged_sessions_prev": 1290, "engagement_rate_prev": 0.702,
      "key_events_prev": 33, "revenue_prev": 740.00,
      "ai_referrals": 156, "ai_referrals_prev": 92,
      "source_counts": { "google": 1402, "chatgpt.com": 98, "claude.ai": 41 }
    }
  ],
  "count": 37
}

{
  "has_monitor": true,
  "best_score": 61,
  "worst_score": 54,
  "monitors": [
    {
      "monitor_id": "vis_2a91", "name": "Brand prompts", "enabled": true,
      "schedule": "weekly", "assistants": ["chatgpt", "claude", "gemini"],
      "last_scan_at": "2026-05-27T09:00:00Z", "next_scan_at": "2026-06-03T09:00:00Z",
      "latest_scan": {
        "scan_id": "vscan_88c1", "visibility_score": 61,
        "citation_rate": 0.34, "share_of_voice": 0.22, "accuracy_flags": 2
      }
    }
  ]
}

[
  {
    "scan_id": "vscan_88c1", "created_at": "2026-05-27T09:01:12Z",
    "assistant": "chatgpt", "prompt_id": "pr_01",
    "prompt_text": "best ai seo tools 2026",
    "answer_text": "…",
    "cited": true, "text_cited": true, "domain_cited": true,
    "position": 2, "matched_alias": "VectraSEO",
    "matched_source": { "url": "https://acme.com/blog/aeo-guide" },
    "sources": ["https://acme.com/blog/aeo-guide"],
    "competitors_cited": ["arvow.com"], "response_accurate": null,
    "model": "gpt-…", "cost_usd": 0.0021, "error": null
  }
]

{
  "has_monitor": true,
  "monitors": [
    {
      "monitor_id": "mon_3c1", "domain": "acme.com", "enabled": true,
      "last_scan_at": "2026-05-29T05:00:00Z", "next_scan_at": "2026-05-30T05:00:00Z",
      "latest_scan": {
        "scan_id": "scan_5b2", "finished_at": "2026-05-29T05:03:41Z",
        "urls_checked": 184, "health_score": 92,
        "issue_counts": { "critical": 0, "warning": 3, "info": 9 },
        "aeo_score": 78,
        "aeo_issue_counts": { "critical": 1, "warning": 4, "info": 6 }
      }
    }
  ]
}

{
  "items": [
    {
      "scan_id": "scan_5b2", "rule_id": "missing_meta",
      "severity": "warning", "category": "seo",
      "url": "https://acme.com/pricing", "url_hash": "…",
      "message": "Page is missing a meta description.",
      "recommendation": "Add a 140-160 char description summarising the page.",
      "evidence": {}
    }
  ],
  "count": 47,
  "next_cursor": null
}

{
  "project_id": "prj_8fa21c",
  "window_days": 30,
  "fetched_at": "2026-05-29T06:00:00Z",
  "schedule": { "cadence": "daily", "interval_hours": 24,
                "last_run_at": "2026-05-29T06:00:00Z", "next_run_at": "2026-05-30T06:00:00Z" },
  "items": [
    {
      "keyword": "answer engine optimization",
      "current_position": 6, "last_fetched_date": "2026-05-29", "current_source": "gsc",
      "history": [
        { "date": "2026-05-23", "position": 9, "source": "gsc" },
        { "date": "2026-05-29", "position": 6, "source": "gsc" }
      ]
    }
  ],
  "top_wins_this_week": [
    { "keyword": "answer engine optimization",
      "current_position": 6, "previous_position": 9, "jump": 3 }
  ]
}

Create and manage projects programmatically

An account API key reaches every project you own and can create new ones. Everything the dashboard does to a project — short of deleting it — is reachable over REST, and over MCP for AI assistants.

Create a key under Settings → API keys, choosing the permissions the integration needs. The raw key is shown once — only its SHA-256 hash is stored, so it cannot be recovered afterwards. Keys are prefixed vsak_, which leaked-credential scanners recognise the way they do ghp_.

Onboard a whole project in one call

POST /api/v1/onboarding takes an account from nothing to a configured, monitored, scheduled project: the project record, content brief, generation policy, competitors, site-health monitor, content schedule and Auto-Pilot policy — together.

curl -X POST https://api.vectraseo.com/api/v1/onboarding \
  -H "x-api-key: vsak_..." -H "content-type: application/json" \
  -d '{
    "project": {
      "business_name": "Acme Robotics",
      "business_url": "https://acmerobotics.com",
      "industry": "Industrial automation",
      "target_audience": "Plant managers at mid-size manufacturers"
    },
    "competitors": ["https://competitor-a.com"],
    "monitor": { "schedule": "daily" },
    "schedule": { "interval_days": 7, "posts_per_run": 2 }
  }'

It answers 202 with a project_id you can use immediately and a job_id to poll at GET /api/v1/onboarding/{job_id}. It is asynchronous because creating a monitor fetches your sitemap, measured at 82.6s on a real sitemap index — well past the gateway's 29s ceiling. The project row itself is written synchronously, so a 202 means the project genuinely exists and a 4xx means nothing was created.

Every step is fault-isolated and reports its own outcome: a sitemap that 404s never costs you the schedule that would have been written after it. A run with failed steps still reports completed — re-apply just those steps with the individual endpoints. Re-running onboarding to retry would create a second project.

Nothing costs money unless you ask

analyze_competitors, run_initial_scan and start_content_run are the only paths that spend model budget or plan quota, and all three default to false. When you do set one, the plan check happens up front — you get a synchronous 403, not a surprise on the invoice.

Permissions

Scopes are chosen when a key is created and are fixed afterwards. Grant the least the integration needs; to change them, create a new key and revoke the old one.

projects:read comes with any write scope, because every write path reads the project first to authorise it.

What no key can do

• Delete a project. Deletion here is a real purge, not a reversible hide, so it stays a signed-in action in the dashboard. There is no scope for it.
• Delete a monitor or a gap. The non-destructive equivalents are programmatic instead — disable the monitor, or reject the gap.
• Manage API keys. Minting and revoking needs a session. Otherwise one leaked key could issue itself a wider one, and rotating the compromised key would not evict the attacker.
• Reveal stored CMS credentials, touch billing, or reach another tenant. A project you do not own returns 404, so a key cannot probe for project ids.

Errors and limits

401 for an unknown, malformed or revoked key (the cases are not distinguished, so a caller cannot probe which applied). 403 names the missing scope, or carries code: "subscription_limit" when the plan is the blocker. 404 means the resource does not exist or is not yours. Quota is per account, in a fixed hourly window shared with the Analytics and Agent APIs, and every response carries X-RateLimit-*.

Drive VectraSEO from an AI assistant

VectraSEO ships a Model Context Protocol server, so an assistant can create, onboard and manage projects directly. Same account key, same permissions as the Provisioning API.

Connect

claude mcp add --transport http vectraseo \
  https://api.vectraseo.com/mcp \
  --header "x-api-key: vsak_..."

Any client that speaks Streamable HTTP can point at that URL with an x-api-key (or Authorization: Bearer) header. For clients that can only launch a stdio subprocess, run npx -y @vectraseo/mcp with VECTRASEO_API_KEY set — a zero-dependency bridge to the same endpoint.

Tools

Safety

Tool calls run through the same REST API with the same credential, so an assistant can never do anything the API would refuse — the scope check, plan gate and ownership check all run in their usual place. Tools that spend budget or write to your live site are flagged destructiveHint so your client can prompt first, and the server tells the assistant to confirm with you before calling them. No tool can delete a project, and no tool can manage API keys — including its own, so a leaked key cannot perpetuate itself.

Continuous SEO health checks

Monitors crawl your sitemap on a schedule (or on demand), run 42 SEO health rules plus 12 AEO readiness checks against every URL, and roll results up into 0–100 SEO health and AEO readiness scores. 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 1,000 URLs and usually complete in 1–5 minutes.

The 54 checks

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.

score = max(0, 100 − (critical × 15) − (warning × 5) − (info × 1))

Issue response shape

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

{
  "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"
}

One-click fixes (live page is the source of truth)

A recommendation or health issue can be turned into a published fix, one page at a time. For a page VectraSEO publishes, the fixer reads your live page as the source of truth (not a stored copy), applies the minimal patch, re-validates it through the same quality gates as a normal publish, then republishes through your CMS adapter and requests a recrawl.

Because the patch is built on the current live version, edits you made outside VectraSEO are kept, not overwritten. If the live page can't be read (it's down or blocked) or its editable content can't be isolated confidently, the fix is skipped rather than applied from an older copy — and the result tells you why. Deterministic fixes (broken links, JSON-LD schema, image alt text) run on any paid plan; model-written fixes (metadata, answer blocks, internal links) require a paid plan with credits.

Supported CMS platforms

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

Publishing to any endpoint

The Custom API adapter lets you ship posts to any REST endpoint. VectraSEO POSTs JSON with the following payload shape. For destinations with product capability rules, expose a public /.well-known/product-capabilities.json contract and save its URL in project settings so unsupported claims can be remediated or held before publish.

{
  "title": "Post Title",
  "seo_title": "Search Result Title",
  "body_html": "<p>Full HTML content...</p>",
  "slug": "post-title",
  "tags": ["seo", "blogging"],
  "meta_description": "Useful search snippet for this post.",
  "excerpt": "Reader-facing post summary.",
  "author": "Author Name",
  "images": [
    {
      "filename": "image.png",
      "data": "<base64-encoded>",
      "alt": "Alt text"
    }
  ],
  "published_at": "2026-04-05T00:00:00Z",
  "status": "published"
}

Configuration fields

Product capability contract

Use this optional public JSON contract to tell VectraSEO which destination-product capabilities are supported, unsupported, planned, beta, deprecated, or unknown.

{
  "schema_version": "1.0",
  "product": { "name": "Emcognito", "aliases": ["Emcognito aliases"] },
  "updated_at": "2026-06-12T00:00:00Z",
  "cache_ttl_seconds": 3600,
  "capabilities": [
    {
      "id": "custom_domains",
      "name": "Custom domains",
      "status": "unsupported",
      "blocked_claims": ["custom domain", "custom domains"],
      "allowed_qualifiers": ["does not support", "planned", "roadmap", "subdomain"],
      "preferred_wording": "Emcognito aliases currently use the shared emcognito.com domain; custom subdomain support is planned, but custom domains are not available today."
    }
  ]
}

Rejection response (tell VectraSEO what to avoid)

When you reject a publish because the post claims something your product can’t back, return 422 with a structured violations array. VectraSEO records each rejected claim on the project and excludes it from future generations. A bare 400 with no body is treated as a transient failure and the same claim may be generated again.

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{
  "error": "capability_claim_violation",
  "message": "Post asserts claims this product cannot back.",
  "violations": [
    {
      "capability_id": "open_source",
      "matched_claim": "open source",
      "status": "unsupported",
      "field": "body_html",
      "preferred_wording": "Sendant's source code is not public; do not describe it as open source."
    }
  ]
}