Developers

Build on AutoSeoPro.aiREST API and MCP connector

Read your websites, articles, backlinks, keywords, audits and stats, make safe article edits, and connect AI assistants such as Claude, Cursor and ChatGPT to your workspace.

Create an API key OpenAPI 3.1 spec Publish to any website

Included in the Growth, Agency, Scale and Enterprise plans

What you can do

Read websites, articles with their full HTML, backlinks, keyword research, technical audit summaries and monthly stats, including Search Console clicks and impressions.
Update an article's title or HTML body and replace its featured image. Every change is a restorable revision and nothing is published automatically.
Connect Claude, Cursor, ChatGPT and other MCP clients so an assistant can work with your SEO data in conversation.
Receive signed webhooks when articles are published, audits finish, backlinks are placed and more.

A key or connection only ever sees the websites of the workspace that created it, or a single website if you limit it.

Authentication

Create a key in Settings → Developers and send it with every request, either as a Bearer token or in the X-API-Key header. A key is shown once, stored only as a hash, can expire, and can be revoked at any time.

Base URL: https://autoseopro.ai/api/v1

Authorization: Bearer rk_…
# or
X-API-Key: rk_…

Each key carries only the scopes you choose. A read scope never allows a change.

Scope	Allows
`sites:read`	List websites
`articles:read`	Read articles and their HTML
`articles:write`	Edit article titles and bodies, replace featured images
`audits:read`	Read technical audit summaries
`keywords:read`	Read keywords and clusters
`reports:read`	Read stats and Search Console summaries
`backlinks:read`	Read backlinks
`metadata:read`	Read SEO title and description proposals
`metadata:write`	Approve or reject metadata proposals (always confirmed first)
`approvals:write`	Approve articles for publishing (always confirmed first)
`generation:write`	Request new articles within the plan (always confirmed first)
`sharing:write`	Create client report share links (always confirmed first)
`notifications:read`	Read notifications
`social:read`	Read the social media plan and results

You can limit a key to one website. Its other websites then answer 403 with the code site_not_allowed.

The API never accepts a browser session. A request that only carries a AutoSeoPro.ai sign-in cookie is refused with the code session_auth_not_supported.

Rate limits

60 requests per minute per API key, REST and MCP combined.
200 article edits per workspace per UTC day (title or body updates and featured-image replacements).
Over a limit you receive 429 with a Retry-After header. Wait that many seconds before trying again.

Pagination

List endpoints take page (starting at 1) and per_page (default 25, maximum 100) and return a pagination object with the total count.

{
  "data": [
    "…"
  ],
  "pagination": {
    "page": 2,
    "per_page": 25,
    "total": 61,
    "total_pages": 3,
    "has_more": true
  }
}

Errors

Every error has the same JSON shape. Branch on code, which is stable; message is guidance for developers and may change.

{
  "error": {
    "code": "insufficient_scope",
    "message": "The API key does not carry the scope this operation needs.",
    "status": 403,
    "request_id": "6f1d2c3b-4a5e-4f60-8a7b-9c0d1e2f3a4b"
  }
}

This reference is generated from the OpenAPI document and is shown in English.

Code	HTTP	Meaning
`unauthorized`	401	Send an API key as `Authorization: Bearer rk_…` or `X-API-Key: rk_…`.
`invalid_token`	401	The API key is not valid.
`token_expired`	401	The API key has expired. Create a new one in Settings → Developers.
`token_revoked`	401	The API key was revoked.
`session_auth_not_supported`	401	The API does not accept browser sessions. Use an API key.
`insufficient_scope`	403	The API key does not carry the scope this operation needs.
`plan_upgrade_required`	403	API access is not included in this workspace's plan.
`subscription_inactive`	403	The workspace subscription is not active.
`site_not_allowed`	403	The API key is limited to a different website.
`actor_not_allowed`	403	The person this connection acts for may not make this change (their role or website access does not allow it).
`not_found`	404	No such resource in this workspace.
`method_not_allowed`	405	That HTTP method is not supported on this path.
`stale_article`	409	The article changed since the content hash you sent. Fetch it again and retry.
`article_busy`	409	The article cannot be edited right now (it is publishing, queued or not eligible for an update).
`not_decidable`	409	This item is no longer waiting for a decision. Read it again to see its current state.
`confirmation_stale`	409	The item changed after the preview. Run the preview again and confirm the new result.
`payload_too_large`	413	The request body is too large.
`unsupported_media_type`	415	Unsupported Content-Type for this operation.
`invalid_request`	422	The request is not valid. See `details`.
`nothing_to_update`	422	Send at least one of `title` or `body_html`.
`unsafe_html`	422	The HTML contains elements or attributes the article editor does not allow.
`protected_links_removed`	422	The edit removes internal links that AutoSeoPro.ai placed. Keep them, or edit the article in AutoSeoPro.ai.
`image_invalid`	422	The image must be a JPEG, PNG, WebP, GIF or AVIF file within the size limit.
`image_fetch_failed`	422	The image URL could not be fetched (it must be a public https URL).
`confirmation_invalid`	422	The confirmation token is not valid for this action or this connection. Run the matching preview first.
`confirmation_expired`	422	The confirmation token has expired or was already used. Run the preview again.
`rate_limited`	429	Too many requests. Slow down and retry after the Retry-After interval.
`edit_quota_exceeded`	429	The daily article-edit allowance for this workspace is used up.
`plan_limit_reached`	429	The plan's allowance for this is used up for the current period.
`internal_error`	500	Something went wrong on our side. Quote the request id if you contact support.
`image_hosting_unavailable`	503	Image uploads are not available on this installation; send a public image URL instead.
`service_unavailable`	503	The service is temporarily unavailable. Retry shortly.

Endpoints

This reference is generated from the OpenAPI document and is shown in English.

GET/sites

List websites

Websites in the workspace that owns the API key. A key limited to one website sees only that website.

Scope: sites:read · MCP tool: list_sites

Parameters
`page`	query · optional	Page number, from 1.
`per_page`	query · optional	Items per page (max 100).

Request

curl "https://autoseopro.ai/api/v1/sites?per_page=25" \
  -H "Authorization: Bearer $AUTOSEOPRO_API_KEY"

Response

{
  "data": [
    {
      "id": "4f1c2a9e-7b1d-4c55-9a51-1f2e3d4c5b6a",
      "name": "Acme Plumbing",
      "domain": "acmeplumbing.com",
      "platform": "wordpress",
      "article_language": "en",
      "created_at": "2026-08-14T09:12:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total": 1,
    "total_pages": 1,
    "has_more": false
  }
}

GET/sites/{site_id}/articles

List articles

Articles for one website, newest first, without their bodies. `from`/`to` filter on the publication date, or the creation date for unpublished articles.

Scope: articles:read · MCP tool: list_articles

Parameters
`site_id`	path · required	Website id (from list sites).
`page`	query · optional	Page number, from 1.
`per_page`	query · optional	Items per page (max 100).
`status`	query · optional	Only articles in this status. (draft, in_review, scheduled, queued, publishing, published, failed)
`from`	query · optional	Earliest date to include: YYYY-MM-DD (UTC, start of day) or an ISO-8601 timestamp.
`to`	query · optional	Latest date to include: YYYY-MM-DD (UTC, inclusive of the whole day) or an ISO-8601 timestamp.

Request

curl "https://autoseopro.ai/api/v1/sites/4f1c2a9e-7b1d-4c55-9a51-1f2e3d4c5b6a/articles?from=2026-09-01&to=2026-09-30&per_page=25" \
  -H "Authorization: Bearer $AUTOSEOPRO_API_KEY"

Response

{
  "data": [
    {
      "id": "9b8e7d6c-5a4b-4c3d-8e2f-1a0b9c8d7e6f",
      "site_id": "4f1c2a9e-7b1d-4c55-9a51-1f2e3d4c5b6a",
      "title": "How to Fix a Leaking Tap",
      "status": "published",
      "target_keyword": "fix leaking tap",
      "word_count": 1640,
      "featured_image_url": "https://acmeplumbing.com/wp-content/uploads/tap.jpg",
      "external_url": "https://acmeplumbing.com/fix-leaking-tap/",
      "published_at": "2026-09-12T08:00:00.000Z",
      "scheduled_for": "2026-09-12T08:00:00.000Z",
      "created_at": "2026-09-10T15:41:00.000Z",
      "content_hash": "3f6c1d0a9b8e7f6d5c4b3a2918f7e6d5c4b3a29180f7e6d5c4b3a29180f7e6d5"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total": 1,
    "total_pages": 1,
    "has_more": false
  }
}

GET/articles/{article_id}

Get an article

One article with its full HTML body, SEO title and meta description, and the content hash to send back with an edit.

Scope: articles:read · MCP tool: get_article

Parameters
`article_id`	path · required	Article id.

Request

curl "https://autoseopro.ai/api/v1/articles/9b8e7d6c-5a4b-4c3d-8e2f-1a0b9c8d7e6f" \
  -H "Authorization: Bearer $AUTOSEOPRO_API_KEY"

Response

{
  "data": {
    "id": "9b8e7d6c-5a4b-4c3d-8e2f-1a0b9c8d7e6f",
    "site_id": "4f1c2a9e-7b1d-4c55-9a51-1f2e3d4c5b6a",
    "title": "How to Fix a Leaking Tap",
    "status": "published",
    "target_keyword": "fix leaking tap",
    "word_count": 1640,
    "featured_image_url": "https://acmeplumbing.com/wp-content/uploads/tap.jpg",
    "external_url": "https://acmeplumbing.com/fix-leaking-tap/",
    "published_at": "2026-09-12T08:00:00.000Z",
    "scheduled_for": "2026-09-12T08:00:00.000Z",
    "created_at": "2026-09-10T15:41:00.000Z",
    "content_hash": "3f6c1d0a9b8e7f6d5c4b3a2918f7e6d5c4b3a29180f7e6d5c4b3a29180f7e6d5",
    "meta_title": "How to Fix a Leaking Tap (Step by Step)",
    "meta_description": "A plumber's guide to stopping a dripping tap in 20 minutes.",
    "body_html": "<h2>What you need</h2><p>An adjustable spanner and a new washer.</p>",
    "revision": 4
  }
}

PUT/articles/{article_id}

Update an article's title or body

Edit the working copy of an article exactly as the AutoSeoPro.ai editor saves it: the HTML is normalised to the editor's allowed subset, unsafe markup is refused, the website's external-link policy is applied, and quality checks are recomputed. Every change is stored as a new revision (source `api`, or `mcp` from the connector) that can be restored from the article page. This never publishes, unpublishes, schedules or changes settings. A published article's working copy can be edited when it is eligible for an update; push it live from AutoSeoPro.ai. Edits that remove internal links AutoSeoPro.ai placed (the related-resources block or tracked contextual links) are refused with `protected_links_removed`. Send `expected_content_hash` (from a read) to refuse the edit with `stale_article` if the article changed in the meantime.

Scope: articles:write · MCP tool: update_article

Parameters
`article_id`	path · required	Article id.
`title`	body · optional	New display title.
`body_html`	body · optional	New article body (HTML).
`reason`	body · optional	Why the change was made; kept in the activity log.
`expected_content_hash`	body · optional	content_hash from your last read.

Request

curl -X PUT "https://autoseopro.ai/api/v1/articles/9b8e7d6c-5a4b-4c3d-8e2f-1a0b9c8d7e6f" \
  -H "Authorization: Bearer $AUTOSEOPRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"How to Fix a Leaking Tap in 20 Minutes","body_html":"<h2>What you need</h2><p>An adjustable spanner, a new washer and 20 minutes.</p>","reason":"Refresh intro","expected_content_hash":"3f6c1d0a9b8e7f6d5c4b3a2918f7e6d5c4b3a29180f7e6d5c4b3a29180f7e6d5"}'

Response

{
  "data": {
    "changed": true,
    "revision": 5,
    "article": {
      "id": "9b8e7d6c-5a4b-4c3d-8e2f-1a0b9c8d7e6f",
      "site_id": "4f1c2a9e-7b1d-4c55-9a51-1f2e3d4c5b6a",
      "title": "How to Fix a Leaking Tap",
      "status": "published",
      "target_keyword": "fix leaking tap",
      "word_count": 1640,
      "featured_image_url": "https://acmeplumbing.com/wp-content/uploads/tap.jpg",
      "external_url": "https://acmeplumbing.com/fix-leaking-tap/",
      "published_at": "2026-09-12T08:00:00.000Z",
      "scheduled_for": "2026-09-12T08:00:00.000Z",
      "created_at": "2026-09-10T15:41:00.000Z",
      "content_hash": "3f6c1d0a9b8e7f6d5c4b3a2918f7e6d5c4b3a29180f7e6d5c4b3a29180f7e6d5",
      "meta_title": "How to Fix a Leaking Tap (Step by Step)",
      "meta_description": "A plumber's guide to stopping a dripping tap in 20 minutes.",
      "body_html": "<h2>What you need</h2><p>An adjustable spanner and a new washer.</p>",
      "revision": 5
    }
  }
}

POST/articles/{article_id}/featured-image

Replace the featured image

Set a new featured image from a public https URL (JSON body), or upload the image bytes directly with an image Content-Type. JPEG, PNG, WebP, GIF or AVIF up to 5 MB. The URL is fetched once from AutoSeoPro.ai's servers (private and internal addresses are refused) and checked to be a real image. Uploaded images are hosted by AutoSeoPro.ai. The change is stored as a restorable revision and never publishes.

Scope: articles:write · MCP tool: replace_featured_image

Parameters
`article_id`	path · required	Article id.
`url`	body · required	Public https URL of the image.
`alt`	body · optional	Alt text. Defaults to the current alt text or the article title.
`expected_content_hash`	body · optional	content_hash from your last read.

Request

curl -X POST "https://autoseopro.ai/api/v1/articles/9b8e7d6c-5a4b-4c3d-8e2f-1a0b9c8d7e6f/featured-image" \
  -H "Authorization: Bearer $AUTOSEOPRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://images.example.com/leaking-tap.jpg","alt":"Dripping kitchen tap"}'

Response

{
  "data": {
    "changed": true,
    "revision": 6,
    "article": {
      "id": "9b8e7d6c-5a4b-4c3d-8e2f-1a0b9c8d7e6f",
      "site_id": "4f1c2a9e-7b1d-4c55-9a51-1f2e3d4c5b6a",
      "title": "How to Fix a Leaking Tap",
      "status": "published",
      "target_keyword": "fix leaking tap",
      "word_count": 1640,
      "featured_image_url": "https://images.example.com/leaking-tap.jpg",
      "external_url": "https://acmeplumbing.com/fix-leaking-tap/",
      "published_at": "2026-09-12T08:00:00.000Z",
      "scheduled_for": "2026-09-12T08:00:00.000Z",
      "created_at": "2026-09-10T15:41:00.000Z",
      "content_hash": "3f6c1d0a9b8e7f6d5c4b3a2918f7e6d5c4b3a29180f7e6d5c4b3a29180f7e6d5",
      "meta_title": "How to Fix a Leaking Tap (Step by Step)",
      "meta_description": "A plumber's guide to stopping a dripping tap in 20 minutes.",
      "body_html": "<h2>What you need</h2><p>An adjustable spanner and a new washer.</p>",
      "revision": 6
    }
  }
}

Upload the image bytes instead

curl -X POST "https://autoseopro.ai/api/v1/articles/9b8e7d6c-5a4b-4c3d-8e2f-1a0b9c8d7e6f/featured-image" \
  -H "Authorization: Bearer $AUTOSEOPRO_API_KEY" \
  -H "Content-Type: image/jpeg" \
  --data-binary @featured.jpg

GET/sites/{site_id}/backlinks

List backlinks

Backlink placements AutoSeoPro.ai earned or recorded for the website, newest first, with their verification state. `from`/`to` filter on when the placement was recorded.

Scope: backlinks:read · MCP tool: list_backlinks

Parameters
`site_id`	path · required	Website id (from list sites).
`page`	query · optional	Page number, from 1.
`per_page`	query · optional	Items per page (max 100).
`state`	query · optional	Only placements in this state. (unverified, verifying, verified, invalid, degraded, removed)
`from`	query · optional	Earliest date to include: YYYY-MM-DD (UTC, start of day) or an ISO-8601 timestamp.
`to`	query · optional	Latest date to include: YYYY-MM-DD (UTC, inclusive of the whole day) or an ISO-8601 timestamp.

Request

curl "https://autoseopro.ai/api/v1/sites/4f1c2a9e-7b1d-4c55-9a51-1f2e3d4c5b6a/backlinks?from=2026-09-01&to=2026-09-30&per_page=25" \
  -H "Authorization: Bearer $AUTOSEOPRO_API_KEY"

Response

{
  "data": [
    {
      "id": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f",
      "source_url": "https://homeguide.example/best-plumbers",
      "title": "Best plumbers in town",
      "target_url": "https://acmeplumbing.com/",
      "state": "verified",
      "provenance": "source_crawled",
      "submitted_at": "2026-09-03T10:00:00.000Z",
      "verified_at": "2026-09-28T06:00:00.000Z",
      "last_checked_at": "2026-09-28T06:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total": 1,
    "total_pages": 1,
    "has_more": false
  }
}

GET/sites/{site_id}/stats

Get website stats

Counts for a reporting period (articles created and published, backlinks verified, keywords tracked) plus the Search Console summary for published articles when Search Console is connected.

Scope: reports:read · MCP tool: get_stats

Parameters
`site_id`	path · required	Website id (from list sites).
`period`	query · optional	this_month, last_month, last_30_days or a calendar month YYYY-MM (UTC). Defaults to this_month.

Request

curl "https://autoseopro.ai/api/v1/sites/4f1c2a9e-7b1d-4c55-9a51-1f2e3d4c5b6a/stats?period=last_month" \
  -H "Authorization: Bearer $AUTOSEOPRO_API_KEY"

Response

{
  "data": {
    "site_id": "4f1c2a9e-7b1d-4c55-9a51-1f2e3d4c5b6a",
    "period": {
      "key": "last_month",
      "start": "2026-08-01T00:00:00.000Z",
      "end": "2026-09-01T00:00:00.000Z"
    },
    "articles": {
      "created": 12,
      "published": 10
    },
    "backlinks": {
      "verified": 3,
      "live_total": 17
    },
    "keywords": {
      "tracked": 84
    },
    "search_console": {
      "connected": true,
      "clicks": 1520,
      "impressions": 48210,
      "tracked_articles": 31,
      "window_start": "2026-08-31",
      "window_end": "2026-09-27"
    }
  }
}

GET/sites/{site_id}/keywords

List keywords

The website's keywords with research metrics, cluster and, when observed, their own Search Console figures. Read-only.

Scope: keywords:read · MCP tool: get_keywords

Parameters
`site_id`	path · required	Website id (from list sites).
`page`	query · optional	Page number, from 1.
`per_page`	query · optional	Items per page (max 100).
`status`	query · optional	added = tracked, candidate = suggested. (candidate, added, rejected, archived)
`cluster_id`	query · optional	Only keywords in this cluster.

Request

curl "https://autoseopro.ai/api/v1/sites/4f1c2a9e-7b1d-4c55-9a51-1f2e3d4c5b6a/keywords?per_page=25" \
  -H "Authorization: Bearer $AUTOSEOPRO_API_KEY"

Response

{
  "data": [
    {
      "id": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
      "keyword": "emergency plumber",
      "status": "added",
      "cluster": {
        "id": "5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b",
        "name": "Emergency services"
      },
      "is_primary": true,
      "search_volume": 2400,
      "difficulty": 38,
      "intent": "transactional",
      "potential": 71.5,
      "priority": null,
      "target_url": null,
      "search_console": {
        "impressions": 3100,
        "clicks": 140,
        "ctr": 0.045,
        "position": 8.2,
        "window_days": 28,
        "observed_at": "2026-09-27T04:00:00.000Z"
      },
      "created_at": "2026-08-15T11:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total": 1,
    "total_pages": 1,
    "has_more": false
  }
}

GET/sites/{site_id}/keyword-clusters

List keyword clusters

Topic clusters with their pillar page and keyword count. Read-only.

Scope: keywords:read

Parameters
`site_id`	path · required	Website id (from list sites).
`page`	query · optional	Page number, from 1.
`per_page`	query · optional	Items per page (max 100).

Request

curl "https://autoseopro.ai/api/v1/sites/4f1c2a9e-7b1d-4c55-9a51-1f2e3d4c5b6a/keyword-clusters?per_page=25" \
  -H "Authorization: Bearer $AUTOSEOPRO_API_KEY"

Response

{
  "data": [
    {
      "id": "5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b",
      "name": "Emergency services",
      "status": "active",
      "is_primary": true,
      "pillar_url": "https://acmeplumbing.com/emergency/",
      "keyword_count": 14,
      "created_at": "2026-08-15T11:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total": 1,
    "total_pages": 1,
    "has_more": false
  }
}

GET/sites/{site_id}/audit

Get the audit summary

Scores and check counts from the latest technical SEO/GEO audit, plus the problems of the latest full-site audit in fix-plan order. Read-only; audits are run from AutoSeoPro.ai. For the full plan, trend and example URLs use the full-site audit endpoints.

Scope: audits:read · MCP tool: get_audit_summary

Parameters
`site_id`	path · required	Website id (from list sites).

Request

curl "https://autoseopro.ai/api/v1/sites/4f1c2a9e-7b1d-4c55-9a51-1f2e3d4c5b6a/audit" \
  -H "Authorization: Bearer $AUTOSEOPRO_API_KEY"

Response

{
  "data": {
    "site_id": "4f1c2a9e-7b1d-4c55-9a51-1f2e3d4c5b6a",
    "audit": {
      "id": "7c8d9e0f-1a2b-4c3d-9e4f-5a6b7c8d9e0f",
      "created_at": "2026-09-25T02:10:00.000Z",
      "scores": {
        "seo": 78,
        "geo": 64,
        "combined": 72
      },
      "findings": {
        "seo": {
          "optimized": 31,
          "quick_win": 4,
          "big_opportunity": 2,
          "needs_api": 1
        },
        "geo": {
          "optimized": 12,
          "quick_win": 3,
          "big_opportunity": 1,
          "needs_api": 0
        }
      }
    },
    "issues": [
      {
        "id": "8d9e0f1a-2b3c-4d4e-8f5a-6b7c8d9e0f1a",
        "category": "performance",
        "rule_id": "lcp_slow",
        "severity": "high",
        "title": "Largest Contentful Paint is slow on mobile",
        "fix_summary": "Compress the hero image."
      }
    ]
  }
}

GET/sites/{site_id}/growth

Get growth history

The website's month-by-month growth record (up to 24 months): Search Console clicks, impressions, CTR, average position, pages with impressions and queries in the top 3/10/100; indexed pages; GA4 sessions; AI visibility. Includes month-over-month and since-start changes. Read-only.

Scope: reports:read

Parameters
`site_id`	path · required	Website id (from list sites).

Request

curl "https://autoseopro.ai/api/v1/sites/4f1c2a9e-7b1d-4c55-9a51-1f2e3d4c5b6a/growth" \
  -H "Authorization: Bearer $AUTOSEOPRO_API_KEY"

Response

{
  "data": {
    "site_id": "4f1c2a9e-7b1d-4c55-9a51-1f2e3d4c5b6a",
    "starting_month": "2026-06",
    "starting_month_source": "first_snapshot",
    "latest_complete_month": "2026-09",
    "months": [
      {
        "month": "2026-09",
        "complete": true,
        "search_console": {
          "state": "ok",
          "data_through": "2026-09-30",
          "clicks": 1520,
          "impressions": 48210,
          "ctr": 0.0315,
          "position": 14.2,
          "pages_with_impressions": 212,
          "queries_top3": 18,
          "queries_top10": 96,
          "queries_top100": 1240,
          "rows_truncated": false
        },
        "index": {
          "state": "no_data",
          "indexed_pages": null,
          "checked_pages": null
        },
        "analytics": {
          "state": "ok",
          "sessions": 4100,
          "users": 3300,
          "organic_sessions": 2050,
          "ai_referral_sessions": 37
        },
        "ai_visibility": {
          "state": "ok",
          "score": 42.5,
          "citation_share": 30
        }
      }
    ],
    "month_over_month": {
      "gsc_clicks": {
        "from": 1310,
        "to": 1520,
        "delta": 210,
        "percent": 16.03
      }
    },
    "since_start": {
      "gsc_clicks": {
        "from": 980,
        "to": 1520,
        "delta": 540,
        "percent": 55.1
      }
    }
  }
}

GET/sites/{site_id}/performance

Get Search Console + GA4 performance

Search Console clicks, impressions, CTR and position (last 28 days vs the 28 before, and last 7 days vs the 7 before), top pages and queries, plus GA4 sessions, AI-assistant referral sessions and top landing pages. Read from AutoSeoPro.ai's stored readings; sections carry a state such as not_connected.

Scope: reports:read · MCP tool: get_performance

Parameters
`site_id`	path · required	Website id (from list sites).

Request

curl "https://autoseopro.ai/api/v1/sites/4f1c2a9e-7b1d-4c55-9a51-1f2e3d4c5b6a/performance" \
  -H "Authorization: Bearer $AUTOSEOPRO_API_KEY"

Response

{
  "data": {
    "site_id": "4f1c2a9e-7b1d-4c55-9a51-1f2e3d4c5b6a",
    "search_console": {
      "state": "ok",
      "fetched_at": "2026-10-03T06:00:00.000Z",
      "stale": false,
      "window": {
        "start": "2026-09-05",
        "end": "2026-10-02"
      },
      "current": {
        "clicks": 1520,
        "impressions": 48210,
        "ctr": 0.0315,
        "position": 14.2
      },
      "previous": {
        "clicks": 1610,
        "impressions": 47100,
        "ctr": 0.0342,
        "position": 13.8
      },
      "last_7_days": {
        "clicks": 310,
        "impressions": 11200
      },
      "previous_7_days": {
        "clicks": 402,
        "impressions": 11900
      },
      "top_pages": [
        {
          "key": "https://acmeplumbing.com/emergency/",
          "clicks": 220,
          "impressions": 5100,
          "ctr": 0.043,
          "position": 6.1
        }
      ],
      "top_queries": [
        {
          "key": "emergency plumber",
          "clicks": 140,
          "impressions": 3100,
          "ctr": 0.045,
          "position": 8.2
        }
      ]
    },
    "analytics": {
      "state": "connected",
      "fetched_at": "2026-10-03T06:00:00.000Z",
      "current": {
        "sessions": 4100,
        "engaged_sessions": 2600,
        "key_events": 41
      },
      "previous": {
        "sessions": 4300,
        "engaged_sessions": 2700,
        "key_events": 44
      },
      "ai_referral_sessions": {
        "current": 37,
        "previous": 29
      },
      "top_landing_pages": [
        {
          "path": "/emergency/",
          "sessions": 820
        }
      ]
    }
  }
}

GET/sites/{site_id}/geo-visibility

Get AI visibility (GEO) and AI visits

The latest and previous completed AI visibility runs (score 0-100, prompts tested, answers citing the website, engines) and AI crawler / AI assistant visits over the last 28 days vs the 28 before, as measured by the WordPress plugin, Cloudflare or the tracking snippet.

Scope: reports:read · MCP tool: get_geo_visibility

Parameters
`site_id`	path · required	Website id (from list sites).

Request

curl "https://autoseopro.ai/api/v1/sites/4f1c2a9e-7b1d-4c55-9a51-1f2e3d4c5b6a/geo-visibility" \
  -H "Authorization: Bearer $AUTOSEOPRO_API_KEY"

Response

{
  "data": {
    "site_id": "4f1c2a9e-7b1d-4c55-9a51-1f2e3d4c5b6a",
    "latest_run": {
      "id": "1b2c3d4e-5f6a-4b7c-8d9e-0f1a2b3c4d5e",
      "run_date": "2026-09-28T03:00:00.000Z",
      "score": 42.5,
      "prompts_tested": 24,
      "cited_answers": 7,
      "failed_prompts": 0,
      "engines": [
        "chatgpt",
        "perplexity",
        "gemini"
      ]
    },
    "previous_run": null,
    "ai_visits": {
      "window_days": 28,
      "sources": [
        "wordpress"
      ],
      "crawler_hits": {
        "current": 410,
        "previous": 350,
        "change_pct": 17
      },
      "assistant_referrals": {
        "current": 37,
        "previous": 29,
        "change_pct": 28
      },
      "top_pages": [
        {
          "path": "/emergency/",
          "hits": 51
        }
      ]
    }
  }
}

GET/sites/{site_id}/metadata-proposals

List metadata proposals

SEO title and meta description proposals for the website's pages, newest first, with what the page served at the time. `state=proposed` lists the ones waiting for a decision.

Scope: metadata:read · MCP tool: list_metadata_proposals

Parameters
`site_id`	path · required	Website id (from list sites).
`page`	query · optional	Page number, from 1.
`per_page`	query · optional	Items per page (max 100).
`state`	query · optional	Only proposals in this state. (proposed, approved, rejected, applied, partially_applied, refused, rolled_back, superseded, assessed)

Request

curl "https://autoseopro.ai/api/v1/sites/4f1c2a9e-7b1d-4c55-9a51-1f2e3d4c5b6a/metadata-proposals?state=proposed&per_page=25" \
  -H "Authorization: Bearer $AUTOSEOPRO_API_KEY"

Response

{
  "data": [
    {
      "id": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c6d",
      "site_id": "4f1c2a9e-7b1d-4c55-9a51-1f2e3d4c5b6a",
      "page_url": "https://acmeplumbing.com/rigid-boxes/",
      "state": "proposed",
      "current": {
        "title": "Rigid boxes",
        "description": null
      },
      "proposed": {
        "title": "Rigid Boxes | Custom Sizes, Fast UK Delivery",
        "description": "Custom rigid boxes made to your size."
      },
      "approved_fields": [],
      "created_at": "2026-10-01T09:00:00.000Z",
      "updated_at": "2026-10-01T09:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total": 1,
    "total_pages": 1,
    "has_more": false
  }
}

GET/sites/{site_id}/backlink-report

Get the backlink report

Links verified live now, lost links, referring domains and, per link where measured, the growth proof: Search Console clicks before vs after the link went live and GA4 referral sessions.

Scope: backlinks:read · MCP tool: get_backlink_report

Parameters
`site_id`	path · required	Website id (from list sites).

Request

curl "https://autoseopro.ai/api/v1/sites/4f1c2a9e-7b1d-4c55-9a51-1f2e3d4c5b6a/backlink-report" \
  -H "Authorization: Bearer $AUTOSEOPRO_API_KEY"

Response

{
  "data": {
    "site_id": "4f1c2a9e-7b1d-4c55-9a51-1f2e3d4c5b6a",
    "summary": {
      "live": 17,
      "lost": 1,
      "referring_domains": 14,
      "growth_available": 6,
      "clicks_delta": 85,
      "referral_sessions": 40
    },
    "links": [
      {
        "linking_page": "https://homeguide.example/best-plumbers",
        "target_url": "https://acmeplumbing.com/",
        "status": "live",
        "first_live_at": "2026-09-03T10:00:00.000Z",
        "growth": {
          "gsc_state": "ok",
          "clicks_before": 120,
          "clicks_after": 160,
          "referral_sessions": 12
        }
      }
    ]
  }
}

GET/sites/{site_id}/client-report-link

Get the client report link state

Whether the website has an active client report share link and when it expires. The link URL is shown only once, when created through preview/apply client report link; no e-mail is ever sent by the API.

Scope: reports:read · MCP tool: get_client_report_link

Parameters
`site_id`	path · required	Website id (from list sites).

Request

curl "https://autoseopro.ai/api/v1/sites/4f1c2a9e-7b1d-4c55-9a51-1f2e3d4c5b6a/client-report-link" \
  -H "Authorization: Bearer $AUTOSEOPRO_API_KEY"

Response

{
  "data": {
    "site_id": "4f1c2a9e-7b1d-4c55-9a51-1f2e3d4c5b6a",
    "active_links": 1,
    "latest": {
      "created_at": "2026-09-20T10:00:00.000Z",
      "expires_at": "2026-10-20T10:00:00.000Z"
    },
    "plan_allows": true
  }
}

GET/notifications

List notifications

Notifications of the person the connection acts for (the API key's creator), newest first; a website-limited key sees only that website's.

Scope: notifications:read · MCP tool: list_notifications

Parameters
`filter`	query · optional	all (default) or unread. (all, unread)
`limit`	query · optional	How many (max 50).

Request

curl "https://autoseopro.ai/api/v1/notifications?filter=unread&per_page=25" \
  -H "Authorization: Bearer $AUTOSEOPRO_API_KEY"

Response

{
  "data": [
    {
      "id": "4d5e6f7a-8b9c-4d0e-9f1a-2b3c4d5e6f7a",
      "type": "content.published",
      "site_id": "4f1c2a9e-7b1d-4c55-9a51-1f2e3d4c5b6a",
      "title": "Article published",
      "body": "How to Fix a Leaking Tap is live.",
      "read": false,
      "created_at": "2026-10-02T09:30:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total": 1,
    "total_pages": 1,
    "has_more": false
  }
}

GET/sites/{site_id}/health

Get site health

Latest usable technical audit scores and the ten highest-priority problems of the latest full-site audit, plus real-user Core Web Vitals (p75 LCP, INP, CLS, TTFB over 28 days, mobile and desktop) for the whole site and for AutoSeoPro.ai article pages vs the rest of the site.

Scope: audits:read · MCP tool: get_site_health

Parameters
`site_id`	path · required	Website id (from list sites).

Request

curl "https://autoseopro.ai/api/v1/sites/4f1c2a9e-7b1d-4c55-9a51-1f2e3d4c5b6a/health" \
  -H "Authorization: Bearer $AUTOSEOPRO_API_KEY"

Response

{
  "data": {
    "site_id": "4f1c2a9e-7b1d-4c55-9a51-1f2e3d4c5b6a",
    "audit": {
      "id": "7c8d9e0f-1a2b-4c3d-9e4f-5a6b7c8d9e0f",
      "created_at": "2026-09-25T02:10:00.000Z",
      "scores": {
        "seo": 78,
        "geo": 64,
        "combined": 72
      }
    },
    "top_issues": [
      {
        "severity": "high",
        "title": "Largest Contentful Paint is slow on mobile",
        "fix_summary": "Compress the hero image."
      }
    ],
    "web_vitals": {
      "enabled": true,
      "days": 28,
      "site": {
        "mobile": {
          "lcp": {
            "p75": 2900,
            "rating": "needs-improvement",
            "samples": 410
          }
        }
      },
      "articles_vs_site": {
        "has_article_data": true,
        "slower": [
          {
            "device": "mobile",
            "metric": "lcp"
          }
        ]
      }
    }
  }
}

GET/sites/{site_id}/crawl

Get the full-site audit and the fix plan

The latest completed full-site audit: site health, what was covered, the prioritised fix plan (fix these 5 first, quick wins, bigger projects, each with why, how, affected pages and example URLs), the health-score history of the stored audits, what is new, fixed or worse since the previous audit, and checks that could not measure something. Read-only; audits are run from AutoSeoPro.ai.

Scope: audits:read · MCP tool: get_crawl_summary

Parameters
`site_id`	path · required	Website id (from list sites).

Request

curl "https://autoseopro.ai/api/v1/sites/4f1c2a9e-7b1d-4c55-9a51-1f2e3d4c5b6a/crawl" \
  -H "Authorization: Bearer $AUTOSEOPRO_API_KEY"

Response

{
  "data": {
    "site_id": "4f1c2a9e-7b1d-4c55-9a51-1f2e3d4c5b6a",
    "crawl": {
      "id": "3c4d5e6f-7a8b-4c9d-8e0f-1a2b3c4d5e6f",
      "finished_at": "2026-10-14T03:12:00.000Z",
      "health_score": 74,
      "pages_crawled": 312,
      "pages_discovered": 340,
      "images_checked": 120,
      "page_budget": 500,
      "budget_reached": false,
      "totals": {
        "errors": 9,
        "warnings": 41,
        "notices": 22
      },
      "issue_types": 11,
      "comparison": {
        "fixed": 6,
        "new": 3,
        "remaining": 28,
        "not_rechecked": 0,
        "previous_finished_at": "2026-09-14T03:10:00.000Z"
      }
    },
    "active_crawl": null,
    "fix_plan": {
      "fix_first": [
        {
          "code": "canonical_to_non_200",
          "title": "Canonical points to a page that does not work",
          "why": "Search engines may ignore the page you want ranked.",
          "how": "Point the canonical tag at the live, final address of the page.",
          "severity": "warning",
          "category": "indexability",
          "impact": "high",
          "effort": "low",
          "group": "fix_first",
          "rank": 1,
          "priority": 12.8,
          "affected_pages": 12,
          "share_of_pages": 0.0385,
          "examples": [
            "https://acmeplumbing.com/emergency/"
          ]
        }
      ],
      "quick_wins": [],
      "bigger_projects": []
    },
    "trend": {
      "verdict": "improved",
      "sample": "similar",
      "score_change": 4,
      "points": [
        {
          "crawl_id": "3c4d5e6f-7a8b-4c9d-8e0f-1a2b3c4d5e6f",
          "finished_at": "2026-10-14T03:12:00.000Z",
          "health_score": 74,
          "pages_crawled": 312,
          "errors": 9,
          "warnings": 41,
          "notices": 22
        }
      ],
      "new_issues": [],
      "fixed_issues": [
        "h1_missing"
      ],
      "regressed_issues": [],
      "improved_issues": []
    },
    "not_measured": []
  }
}

GET/sites/{site_id}/crawl/issues

List full-site audit issues

Every kind of problem the latest completed full-site audit found, highest priority first, each with why, how, affected-page count and example URLs. Filter by severity, impact or area. Read-only.

Scope: audits:read · MCP tool: list_crawl_issues

Parameters
`site_id`	path · required	Website id (from list sites).
`severity`	query · optional	Only this severity. (error, warning, notice)
`impact`	query · optional	Only issues of this impact (what fixing them is worth). (high, medium, low)
`category`	query · optional	Only this area of the site. (crawlability, indexability, links, metadata, content, images, structured_data, international, performance, security, accessibility, mobile, ai_readiness)
`page`	query · optional	Page number, from 1.
`per_page`	query · optional	Items per page (max 100).

Request

curl "https://autoseopro.ai/api/v1/sites/4f1c2a9e-7b1d-4c55-9a51-1f2e3d4c5b6a/crawl/issues?severity=error&impact=high&category=indexability&per_page=25" \
  -H "Authorization: Bearer $AUTOSEOPRO_API_KEY"

Response

{
  "data": [
    {
      "code": "canonical_to_non_200",
      "title": "Canonical points to a page that does not work",
      "why": "Search engines may ignore the page you want ranked.",
      "how": "Point the canonical tag at the live, final address of the page.",
      "severity": "warning",
      "category": "indexability",
      "impact": "high",
      "effort": "low",
      "group": "fix_first",
      "rank": 1,
      "priority": 12.8,
      "affected_pages": 12,
      "share_of_pages": 0.0385,
      "examples": [
        "https://acmeplumbing.com/emergency/"
      ]
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total": 1,
    "total_pages": 1,
    "has_more": false
  }
}

GET/sites/{site_id}/crawl/issues/{issue_code}/urls

List the URLs affected by one issue

The URLs the latest completed full-site audit found with one issue (50 per page, most linked-to first), optionally one page type. Only the latest audit keeps its per-URL results. Read-only.

Scope: audits:read · MCP tool: list_crawl_issue_urls

Parameters
`site_id`	path · required	Website id (from list sites).
`issue_code`	path · required	Issue code (from list full-site audit issues).
`page_type`	query · optional	Only URLs of this page type. (home, product, category, service, location, blog_post, blog_index, page, custom, tag, pagination, filtered, utility)
`page`	query · optional	Page number, from 1.

Request

curl "https://autoseopro.ai/api/v1/sites/4f1c2a9e-7b1d-4c55-9a51-1f2e3d4c5b6a/crawl/issues/title_missing/urls?page_type=product&per_page=25" \
  -H "Authorization: Bearer $AUTOSEOPRO_API_KEY"

Response

{
  "data": [
    {
      "url": "https://acmeplumbing.com/emergency/",
      "page_type": "service",
      "http_status": 200,
      "final_status": 200,
      "final_url": null,
      "title": "Emergency plumbing",
      "internal_links_in": 14,
      "linked_from": [
        "https://acmeplumbing.com/"
      ],
      "crawl_depth": 1,
      "words": 540
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 50,
    "total": 1,
    "total_pages": 1,
    "has_more": false
  }
}

GET/sites/{site_id}/social/plan

Get the social media plan

The Social Media Autopilot add-on tier in force for the website and its Social AI Manager plan for the coming days (default 7, max 31): the brief's content pillars and cadence, and the rolling plan board — one idea per card with its posts on each platform (time, status, caption excerpt), whether it is approved, awaiting approval, locked (inside the 24-hour lock) or being regenerated. Read-only.

Scope: social:read · MCP tool: get_social_plan

Parameters
`site_id`	path · required	Website id (from list sites).
`days`	query · optional	How many days ahead (1-31).

Request

curl "https://autoseopro.ai/api/v1/sites/4f1c2a9e-7b1d-4c55-9a51-1f2e3d4c5b6a/social/plan?days=7" \
  -H "Authorization: Bearer $AUTOSEOPRO_API_KEY"

Response

{
  "data": {
    "site_id": "4f1c2a9e-7b1d-4c55-9a51-1f2e3d4c5b6a",
    "add_on": {
      "tier": "pro",
      "state": "active",
      "grace_ends_at": null
    },
    "approval_mode": "approve_first",
    "lock_hours": 24,
    "brief": {
      "status": "confirmed",
      "confirmed": true,
      "pillars": [
        {
          "pillar": "educate",
          "share": 40
        },
        {
          "pillar": "promote",
          "share": 30
        }
      ],
      "cadence": {
        "perWeek": 3
      },
      "goals": [
        "leads"
      ],
      "learned_adjusted": false
    },
    "window": {
      "from": "2026-10-04T00:00:00.000Z",
      "to": "2026-10-11T00:00:00.000Z",
      "days": 7
    },
    "ideas": [
      {
        "id": "1c2d3e4f-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
        "at": "2026-10-06T09:00:00.000Z",
        "title": "Fix a dripping tap in 20 minutes",
        "pillar": "educate",
        "locked": false,
        "approved": false,
        "awaiting_approval": true,
        "regenerating": false,
        "posts": [
          {
            "id": "6f7a8b9c-0d1e-4f2a-8b3c-4d5e6f7a8b9c",
            "platform": "facebook",
            "format": "image",
            "scheduled_at": "2026-10-06T09:00:00.000Z",
            "status": "scheduled",
            "approved": false,
            "locked": false,
            "caption_excerpt": "Dripping tap? Here is the 20-minute fix.",
            "link": "https://acmeplumbing.com/fix-leaking-tap/",
            "image_mode": "template",
            "ai_generated": true
          }
        ]
      }
    ],
    "posts": [
      {
        "id": "6f7a8b9c-0d1e-4f2a-8b3c-4d5e6f7a8b9c",
        "platform": "facebook",
        "format": "image",
        "scheduled_at": "2026-10-06T09:00:00.000Z",
        "status": "scheduled",
        "approved": false,
        "locked": false,
        "pillar": "educate",
        "caption_excerpt": "Dripping tap? Here is the 20-minute fix.",
        "link": "https://acmeplumbing.com/fix-leaking-tap/"
      }
    ]
  }
}

GET/sites/{site_id}/social/results

Get social media results

Totals for posts published in the period (default the last 30 days): impressions, reach, engagements, clicks and video views by platform, ideas per content pillar, plus the latest published posts with their links.

Scope: social:read · MCP tool: list_social_results

Parameters
`site_id`	path · required	Website id (from list sites).
`from`	query · optional	Earliest publication date to include: YYYY-MM-DD (UTC, start of day) or an ISO-8601 timestamp.
`to`	query · optional	Latest publication date to include: YYYY-MM-DD (UTC, inclusive of the whole day) or an ISO-8601 timestamp.

Request

curl "https://autoseopro.ai/api/v1/sites/4f1c2a9e-7b1d-4c55-9a51-1f2e3d4c5b6a/social/results?from=2026-09-01&to=2026-09-30" \
  -H "Authorization: Bearer $AUTOSEOPRO_API_KEY"

Response

{
  "data": {
    "site_id": "4f1c2a9e-7b1d-4c55-9a51-1f2e3d4c5b6a",
    "period": {
      "from": "2026-09-04T00:00:00.000Z",
      "to": "2026-10-04T00:00:00.000Z"
    },
    "totals": {
      "posts": 12,
      "impressions": 8400,
      "reach": 6100,
      "engagements": 390,
      "clicks": 75,
      "video_views": 0
    },
    "by_platform": [
      {
        "platform": "facebook",
        "posts": 6,
        "impressions": 5100,
        "engagements": 240,
        "clicks": 41
      }
    ],
    "ideas_by_pillar": [
      {
        "pillar": "educate",
        "ideas": 5
      }
    ],
    "recent_posts": [
      {
        "platform": "facebook",
        "published_at": "2026-10-02T09:00:00.000Z",
        "external_url": "https://facebook.example/post/1"
      }
    ]
  }
}

POST/metadata-proposals/{proposal_id}/preview-decision

Preview approving or rejecting a metadata proposal

Shows exactly which title/description would be approved (or that the proposal would be rejected) and returns a confirmation token valid for 10 minutes. Changes nothing. Approval does not by itself change the live page: AutoSeoPro.ai applies approved metadata through the website connection as configured.

Scope: metadata:write · MCP tool: preview_metadata_proposal_decision

Parameters
`proposal_id`	path · required	Metadata proposal id (from list metadata proposals).
`decision`	body · required	(approve, reject)
`fields`	body · optional	Fields to approve (default every proposed field).
`note`	body · optional	Why it is rejected (kept with the proposal).

Request

curl -X POST "https://autoseopro.ai/api/v1/metadata-proposals/2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c6d/preview-decision" \
  -H "Authorization: Bearer $AUTOSEOPRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"decision":"approve","fields":["title","description"]}'

Response

{
  "data": {
    "action": "metadata_proposal_decision",
    "will_change": true,
    "summary": {
      "proposal_id": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c6d",
      "page_url": "https://acmeplumbing.com/rigid-boxes/",
      "decision": "approve",
      "fields": [
        "title"
      ],
      "from": {
        "title": "Rigid boxes"
      },
      "to": {
        "title": "Rigid Boxes | Custom Sizes, Fast UK Delivery"
      }
    },
    "blocked_reason": null,
    "confirmation_token": "rkcf_example",
    "expires_at": "2026-10-04T10:10:00.000Z"
  }
}

POST/metadata-proposals/{proposal_id}/apply-decision

Apply a previewed metadata decision

Records the approval or rejection exactly as previewed. CHANGES DATA. Requires the confirmation token from the preview (same connection, within 10 minutes, single use); refused with confirmation_stale if the proposal changed meanwhile.

Scope: metadata:write · MCP tool: apply_metadata_proposal_decision

Parameters
`proposal_id`	path · required	Metadata proposal id (from list metadata proposals).
`confirmation_token`	body · required	Token returned by the matching preview (valid 10 minutes, single use, only for the connection that previewed).

Request

curl -X POST "https://autoseopro.ai/api/v1/metadata-proposals/2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c6d/apply-decision" \
  -H "Authorization: Bearer $AUTOSEOPRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"confirmation_token":"rkcf_AbCdEf0123456789…"}'

Response

{
  "data": {
    "action": "metadata_proposal_decision",
    "applied": true,
    "result": {
      "proposal_id": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c6d",
      "state": "approved"
    }
  }
}

POST/articles/{article_id}/preview-approval

Preview approving an article for publishing

Shows the article, its current status and what approval would do (scheduled articles keep their date; others become ready to publish), plus the latest human fact-check status. Returns a confirmation token. Changes nothing. Fact-checks are recorded by a person in AutoSeoPro.ai, never through the API.

Scope: approvals:write · MCP tool: preview_article_approval

Parameters
`article_id`	path · required	Article id.

Request

curl -X POST "https://autoseopro.ai/api/v1/articles/9b8e7d6c-5a4b-4c3d-8e2f-1a0b9c8d7e6f/preview-approval" \
  -H "Authorization: Bearer $AUTOSEOPRO_API_KEY"

Response

{
  "data": {
    "action": "article_approval",
    "will_change": true,
    "summary": {
      "article_id": "9b8e7d6c-5a4b-4c3d-8e2f-1a0b9c8d7e6f",
      "title": "How to Fix a Leaking Tap",
      "status": "draft",
      "status_after": "in_review",
      "scheduled_for": null,
      "fact_check": "verified"
    },
    "blocked_reason": null,
    "confirmation_token": "rkcf_example",
    "expires_at": "2026-10-04T10:10:00.000Z"
  }
}

POST/articles/{article_id}/apply-approval

Approve an article for publishing (confirmed)

Records the approval previewed by preview approval, as the person the connection acts for. CHANGES DATA and lets AutoSeoPro.ai publish the article on its schedule. Requires the preview's confirmation token; refused if the article changed after the preview.

Scope: approvals:write · MCP tool: apply_article_approval

Parameters
`article_id`	path · required	Article id.
`confirmation_token`	body · required	Token returned by the matching preview (valid 10 minutes, single use, only for the connection that previewed).

Request

curl -X POST "https://autoseopro.ai/api/v1/articles/9b8e7d6c-5a4b-4c3d-8e2f-1a0b9c8d7e6f/apply-approval" \
  -H "Authorization: Bearer $AUTOSEOPRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"confirmation_token":"rkcf_AbCdEf0123456789…"}'

Response

{
  "data": {
    "action": "article_approval",
    "applied": true,
    "result": {
      "article_id": "9b8e7d6c-5a4b-4c3d-8e2f-1a0b9c8d7e6f",
      "status": "in_review"
    }
  }
}

POST/sites/{site_id}/article-requests/preview

Preview requesting a new article

Checks a tracked keyword (by id or exact text) and the plan's article allowance, and returns a confirmation token. Changes nothing. Keywords must already be tracked in AutoSeoPro.ai.

Scope: generation:write · MCP tool: preview_article_request

Parameters
`site_id`	path · required	Website id (from list sites).
`keyword_id`	body · optional	Tracked keyword id (from get_keywords).
`keyword`	body · optional	Exact keyword text, when no id is given.

Request

curl -X POST "https://autoseopro.ai/api/v1/sites/4f1c2a9e-7b1d-4c55-9a51-1f2e3d4c5b6a/article-requests/preview" \
  -H "Authorization: Bearer $AUTOSEOPRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"keyword":"emergency plumber"}'

Response

{
  "data": {
    "action": "article_request",
    "will_change": true,
    "summary": {
      "site_id": "4f1c2a9e-7b1d-4c55-9a51-1f2e3d4c5b6a",
      "keyword_id": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
      "keyword": "emergency plumber",
      "monthly_limit": 90,
      "monthly_used": 41,
      "monthly_remaining": 49,
      "pack_credits": 0
    },
    "blocked_reason": null,
    "confirmation_token": "rkcf_example",
    "expires_at": "2026-10-04T10:10:00.000Z"
  }
}

POST/sites/{site_id}/article-requests/apply

Request a new article (confirmed)

Queues article generation for the previewed keyword, using one article from the plan allowance. CHANGES DATA. The article arrives as a draft for review; it is never published without approval. Requires the preview's confirmation token.

Scope: generation:write · MCP tool: apply_article_request

Parameters
`site_id`	path · required	Website id (from list sites).
`confirmation_token`	body · required	Token returned by the matching preview (valid 10 minutes, single use, only for the connection that previewed).

Request

curl -X POST "https://autoseopro.ai/api/v1/sites/4f1c2a9e-7b1d-4c55-9a51-1f2e3d4c5b6a/article-requests/apply" \
  -H "Authorization: Bearer $AUTOSEOPRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"confirmation_token":"rkcf_AbCdEf0123456789…"}'

Response

{
  "data": {
    "action": "article_request",
    "applied": true,
    "result": {
      "job_id": "5f6a7b8c-9d0e-4f1a-8b2c-3d4e5f6a7b8c",
      "state": "queued"
    }
  }
}

POST/sites/{site_id}/client-report-link/preview

Preview creating a client report link

Shows which report sections a new client share link would include (default all) and that it is valid for 30 days. Returns a confirmation token. Changes nothing. No e-mail is sent.

Scope: sharing:write · MCP tool: preview_client_report_link

Parameters
`site_id`	path · required	Website id (from list sites).
`sections`	body · optional	Report sections (default all).

Request

curl -X POST "https://autoseopro.ai/api/v1/sites/4f1c2a9e-7b1d-4c55-9a51-1f2e3d4c5b6a/client-report-link/preview" \
  -H "Authorization: Bearer $AUTOSEOPRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sections":["performance","visibility","backlinks"]}'

Response

{
  "data": {
    "action": "client_report_link",
    "will_change": true,
    "summary": {
      "site_id": "4f1c2a9e-7b1d-4c55-9a51-1f2e3d4c5b6a",
      "sections": [
        "performance",
        "visibility",
        "backlinks"
      ],
      "valid_days": 30
    },
    "blocked_reason": null,
    "confirmation_token": "rkcf_example",
    "expires_at": "2026-10-04T10:10:00.000Z"
  }
}

POST/sites/{site_id}/client-report-link/apply

Create a client report link (confirmed)

Creates the previewed client report link and returns its URL once (AutoSeoPro.ai keeps only a fingerprint). CHANGES DATA: anyone with the link can view the report until it expires or is revoked in AutoSeoPro.ai. No e-mail is sent.

Scope: sharing:write · MCP tool: apply_client_report_link

Parameters
`site_id`	path · required	Website id (from list sites).
`confirmation_token`	body · required	Token returned by the matching preview (valid 10 minutes, single use, only for the connection that previewed).

Request

curl -X POST "https://autoseopro.ai/api/v1/sites/4f1c2a9e-7b1d-4c55-9a51-1f2e3d4c5b6a/client-report-link/apply" \
  -H "Authorization: Bearer $AUTOSEOPRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"confirmation_token":"rkcf_AbCdEf0123456789…"}'

Response

{
  "data": {
    "action": "client_report_link",
    "applied": true,
    "result": {
      "url": "https://autoseopro.ai/client/AbCdEf",
      "expires_at": "2026-11-03T10:00:00.000Z"
    }
  }
}

Safe edits and revisions

Article HTML goes through the same pipeline as the AutoSeoPro.ai editor: it is normalised to the editor's allowed elements, unsafe markup is refused (unsafe_html), and your website's external-link policy is applied.
Edits that remove internal links AutoSeoPro.ai placed, either the related-resources block or links tracked by internal linking, are refused with protected_links_removed. Moving them or changing their anchor text is fine.
Send expected_content_hash from your last read so an edit never overwrites someone else's change (stale_article).
Every change is stored as a revision marked API or MCP connector. Open the article in AutoSeoPro.ai to see its history and restore any earlier version.
The API never publishes, unpublishes, schedules or deletes articles, and never changes settings.
Every call is recorded in the workspace activity log with the key, the operation, the website and the result.
Other changes (approving metadata or articles, requesting articles, creating client report links) are two-step: a preview changes nothing and returns a confirmation token valid for 10 minutes; the matching apply call makes the change, once, for the same key.

Webhooks

Add endpoints in Settings → Developers and choose the events you want. AutoSeoPro.ai sends a signed JSON POST to your HTTPS endpoint, retries failures with backoff, and pauses an endpoint that keeps failing.

Events

article.publishedarticle.generation_failedaudit.completedgeo.run_completedbacklink.placedreport.deliveredbilling.subscription_changed

Each delivery carries the headers rankora-signature, rankora-timestamp (milliseconds), rankora-event and rankora-event-id.

The body names the event and the website; it never contains article text. Use the API to fetch the details.

{
  "id": "3f9c0b1e7a2d4c5b8e6f1a2b3c4d5e6f",
  "type": "article.published",
  "occurredAt": "2026-10-02T09:30:00.000Z",
  "data": {
    "siteId": "4f1c2a9e-7b1d-4c55-9a51-1f2e3d4c5b6a",
    "notificationType": "content.published"
  }
}

Verify every delivery: compute HMAC-SHA256 over "timestamp.raw body" with your signing secret, compare it in constant time with the hex rankora-signature header, and reject timestamps older than five minutes.

Node.js

import { createHmac, timingSafeEqual } from "node:crypto";

// rawBody: the exact request body string, before JSON.parse
export function verifyAutoSeoProWebhook(rawBody, headers, secret) {
  const timestamp = Number(headers["rankora-timestamp"]);
  if (!Number.isFinite(timestamp) || Math.abs(Date.now() - timestamp) > 5 * 60_000) return false;
  const expected = createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest();
  const given = Buffer.from(String(headers["rankora-signature"] ?? ""), "hex");
  return given.length === expected.length && timingSafeEqual(given, expected);
}

MCP connector

The AutoSeoPro.ai MCP server lets AI assistants use the API as tools. A connection can only see the websites of the workspace that authorised it.

Step-by-step connector guide

Server URL: https://autoseopro.ai/api/mcp

Tools

list_sitesList the websites this AutoSeoPro.ai connection can see. Call this first to get site ids for the other tools.
list_articlesList a website's articles (id, title, status, dates, live URL), newest first. Filter by status or date range.
get_articleGet one article with its full HTML body, SEO title, meta description and content_hash.
update_articleChange an article's title and/or HTML body. Saved as a restorable revision; never publishes. Refused if it removes internal links AutoSeoPro.ai placed. Pass expected_content_hash from get_article to avoid overwriting someone else's change.
replace_featured_imageReplace an article's featured image with a public https image URL. Saved as a restorable revision; never publishes.
list_backlinksList backlinks AutoSeoPro.ai earned or recorded for a website, with live verification state. Filter by state or date range.
get_statsGet a website's numbers for a period (this_month, last_month, last_30_days or YYYY-MM): articles, backlinks, keywords and the Search Console clicks/impressions summary.
get_keywordsList a website's keywords with volume, difficulty, intent, cluster and Search Console position/clicks. Filter by status or cluster.
get_audit_summaryGet the latest technical SEO/GEO audit scores, check counts and open issues for a website.
get_performanceGet a website's Google Search Console and GA4 numbers: last 28 days vs the 28 before, last 7 days vs the 7 before, top pages and queries, sessions and AI-assistant referrals. Use it to explain traffic changes; it never estimates.
get_geo_visibilityGet a website's latest AI visibility (GEO) run score and citations, and AI crawler / AI assistant visits for the last 28 days.
list_metadata_proposalsList a website's SEO title / meta description proposals (page URL, current vs proposed, state). Filter state=proposed for the ones awaiting a decision.
get_backlink_reportGet verified live backlinks, lost links, referring domains and the measured growth each link brought (Search Console before/after, GA4 referrals).
get_client_report_linkCheck whether a website has an active client report share link and when it expires. To create a new link, use preview_client_report_link then apply_client_report_link.
list_notificationsList recent AutoSeoPro.ai notifications (published articles, audits, alerts) for the connected person; filter unread.
get_site_healthGet a website's latest technical audit scores and top issues plus real-user Core Web Vitals, including whether AutoSeoPro.ai article pages are slower than the rest of the site. Use it for 'what should I fix first?'.
get_crawl_summaryGet the latest full-site audit of a website: site health, the prioritised fix plan (fix these first, quick wins, bigger projects), the trend since the previous audits and what could not be measured. Use it for 'what should I fix first?'.
list_crawl_issuesList the problems found by a website's latest full-site audit, highest priority first, with why, how, affected pages and example URLs. Filter by severity, impact or area.
list_crawl_issue_urlsList the URLs affected by one full-site audit issue (use an issue code from list_crawl_issues), 50 per page, most linked-to first; optionally one page type.
get_social_planShow a website's Social AI Manager plan (next 7 days by default): ideas with their pillar, posts per platform, time, caption excerpt and approval/lock state, plus the brief's pillar mix and cadence. Read-only.
list_social_resultsGet a website's social media results for a period (default last 30 days): posts, impressions, reach, engagements and clicks by platform. Read-only.
preview_metadata_proposal_decisionStep 1 of 2 to approve or reject a metadata proposal: shows what would change and returns a confirmation_token. Changes nothing. Show the preview to the user and only call apply_metadata_proposal_decision after they explicitly confirm.
apply_metadata_proposal_decisionStep 2 of 2. CHANGES DATA: records the approval/rejection previewed by preview_metadata_proposal_decision. Requires its confirmation_token. Only call after the user explicitly confirmed the preview.
preview_article_approvalStep 1 of 2 to approve an article for publishing: shows the article and what approval would do, returns a confirmation_token. Changes nothing. Fact-checking cannot be done here (people do it in AutoSeoPro.ai).
apply_article_approvalStep 2 of 2. CHANGES DATA: approves the article previewed by preview_article_approval so it can be published. Requires its confirmation_token. Only call after the user explicitly confirmed.
preview_article_requestStep 1 of 2 to have AutoSeoPro.ai write a new article for a tracked keyword: checks the keyword and the plan allowance, returns a confirmation_token. Changes nothing.
apply_article_requestStep 2 of 2. CHANGES DATA and uses plan allowance: queues the article previewed by preview_article_request. Requires its confirmation_token. Only call after the user explicitly confirmed.
preview_client_report_linkStep 1 of 2 to create a shareable client report link (anyone with the link can view the report for 30 days): shows the sections, returns a confirmation_token. Changes nothing; no e-mail is sent.
apply_client_report_linkStep 2 of 2. CHANGES DATA: creates the shareable client report link previewed by preview_client_report_link and returns its URL. Requires its confirmation_token. Only call after the user explicitly confirmed.

Claude (claude.ai and Claude Desktop)

Open Settings → Connectors → Add custom connector, paste the server URL, then sign in to AutoSeoPro.ai and click Allow.

https://autoseopro.ai/api/mcp

ChatGPT

Open Settings → Apps & Connectors → Advanced settings and turn on Developer mode. Then create a connector, paste the server URL, choose OAuth, sign in to AutoSeoPro.ai and click Allow.

https://autoseopro.ai/api/mcp

Claude Code

Run this in your terminal with an API key from Settings → Developers:

claude mcp add --transport http autoseopro https://autoseopro.ai/api/mcp \
  --header "Authorization: Bearer $AUTOSEOPRO_API_KEY"

Cursor

Add this to ~/.cursor/mcp.json (or .cursor/mcp.json in a project). Without the headers entry, Cursor signs in with OAuth instead.

{
  "mcpServers": {
    "autoseopro": {
      "url": "https://autoseopro.ai/api/mcp",
      "headers": {
        "Authorization": "Bearer rk_your_api_key"
      }
    }
  }
}

Any client that supports Streamable HTTP works with an Authorization: Bearer header carrying an API key. Clients that support OAuth discover the sign-in automatically.

An OAuth connection creates a 30-day API key named after the app. It appears in Settings → Developers, where you can revoke it at any time.

Publish to your own site

Not on WordPress or Webflow? Build a small receiver and AutoSeoPro.ai publishes, updates and deletes articles on your own site through a signed, idempotent API. The guide covers the five setup steps, the headers, the signature, the exact replies and copy-paste kits for Node.js, PHP and Python.

Read the publishing guide

OpenAPI

The full machine-readable description, generated from the same source as the API itself. Import it into Postman, Insomnia or a code generator.

Download openapi.json