Each local area page used to take us half a day to create and optimize.
With SEOmatic, we can create hundreds of pages in the same time, which helps our clients make the best use of their budget.
It's transformed how we deliver scalable SEO solutions.
Will Hawkins
Marketing Director, Digi-Business UK
Agents read your Search Console data, do the work, and prove what actually moved. You decide what ships.
14-Day Free Trial. $1 card check, refunded. Cancel Anytime.
Table of Contents
Base URL https://app.seomatic.ai/api/v1. Bearer auth, JSON in and out. Everything an agent can do is a single endpoint over HTTP, including every tool as POST /tools/{name}.
Send your workspace key as a Bearer token. Keys carry scopes: read:gsc and chat:ask are free; agents:act is paid.
Authorization: Bearer smk_live_...
Limits are per key: up to 500 requests per minute. Every response carries the headers below; a 429 adds Retry-After. Back off and retry after it.
| Header | Meaning |
|---|---|
X-RateLimit-Limit | The ceiling for the window (500). |
X-RateLimit-Remaining | Requests left in the window. |
X-RateLimit-Reset | Unix seconds when the window resets. |
Retry-After | Seconds to wait, sent only on a 429. |
HTTP/1.1 429 Too Many Requests
Retry-After: 30
X-RateLimit-Limit: 500
X-RateLimit-Remaining: 0
{ "error": "Rate limit exceeded", "code": "RATE_LIMITED" }Every error is JSON with a stable code, a human error message, and often a details object. Branch on the code, not the message.
{
"error": "This API key does not have the 'agents:act' scope",
"code": "MISSING_SCOPE",
"details": { "required": "agents:act", "granted": ["read:gsc"] }
}| Code | HTTP | When | How to fix |
|---|---|---|---|
INVALID_API_KEY | 401 | Missing, malformed, or revoked key. | Send a valid `Authorization: Bearer smk_live_...`. Mint keys in the dashboard. |
MISSING_SCOPE | 403 | The key lacks the scope a call needs (e.g. agents:act). | Use a key with the required scope. The body's `details.required` names it. |
REST_ACT_REQUIRES_INFRA | 402 | An acting tool was called over REST on a plan below Infrastructure. | Upgrade to Infrastructure to act over REST, or act over MCP (any paid plan). |
WEBHOOKS_NOT_ENTITLED | 402 | Webhook management on a plan without webhooks. | Webhooks are on the Infrastructure plan. |
ZAPIER_NOT_ENTITLED | 402 | A Zapier endpoint on a plan below Scale. | The Zapier integration is on Scale and above. |
INVALID_ARGUMENTS | 400 | The request body failed the tool's or endpoint's schema. | Check `details` for the failing fields against the parameter table. |
UNKNOWN_TOOL | 404 | No such tool, or the key's scopes don't include it. | List callable tools with GET /v1/tools; the roster is scope-filtered. |
GSC_NOT_CONNECTED | 409 | A GSC read on a workspace with no Search Console property linked. | Connect Google Search Console in the dashboard, then retry. |
GSC_UPSTREAM_ERROR | 502 | Google Search Console returned an error. | Transient upstream issue; retry with backoff. |
TOOL_FAILED | 502 | The tool or a provider it called failed at runtime. | The transport worked; retry, and check `details` for the cause. |
Discover the key, its scopes, plan capabilities, and tools.
/meIntrospect the calling key: workspace, environment, scopes, and the plan capabilities that gate the paid REST/Zapier surface (so an agent can discover entitlements without triggering a 402).
| Status | Description |
|---|---|
200 | Key and workspace details |
401 | Missing or invalid API key |
429 | Rate limited (per key). Retry-After header set. |
curl -X GET https://app.seomatic.ai/api/v1/me \ -H "Authorization: Bearer smk_live_..."
/toolsList every tool this key can call (name, description, input JSON Schema, acts flag): the full REST capability surface, identical to MCP.
| Status | Description |
|---|---|
200 | Scope-filtered tool roster. Each: {name, description, input_schema, acts}. |
401 | Missing or invalid API key |
429 | Rate limited (per key). Retry-After header set. |
curl -X GET https://app.seomatic.ai/api/v1/tools \ -H "Authorization: Bearer smk_live_..."
Your own Search Console property: queries, pages, dimensions, comparisons.
/gsc/top-queriesTop search queries from the workspace's Google Search Console property.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
days | query | integer | no | Lookback window in days (1-90, default 28, finalized-data anchored). |
limit | query | integer | no | Max rows (1-100, default 25). |
| Status | Description |
|---|---|
200 | Query rows with clicks/impressions/ctr/position |
401 | Missing or invalid API key |
403 | Key lacks the 'read:gsc' scope |
409 | Workspace has no GSC property connected |
429 | Rate limited (per key). Retry-After header set. |
curl -X GET https://app.seomatic.ai/api/v1/gsc/top-queries \ -H "Authorization: Bearer smk_live_..."
/gsc/top-pagesTop pages from the workspace's Google Search Console property.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
days | query | integer | no | Lookback window in days (1-90, default 28, finalized-data anchored). |
limit | query | integer | no | Max rows (1-100, default 25). |
| Status | Description |
|---|---|
200 | Page rows with clicks/impressions/ctr/position |
401 | Missing or invalid API key |
403 | Key lacks the 'read:gsc' scope |
409 | Workspace has no GSC property connected |
429 | Rate limited (per key). Retry-After header set. |
curl -X GET https://app.seomatic.ai/api/v1/gsc/top-pages \ -H "Authorization: Bearer smk_live_..."
/tools/get_search_queriesreadGet the top search queries from Google Search Console for the connected website. Returns queries with clicks, impressions, CTR, and average position. Use this to understand what keywords the site ran…
| Name | Type | Required | Description |
|---|---|---|---|
days | number | no | Number of days to look back (1-90, default 28) |
limit | number | no | Number of results to return (1-5000, default 50). Use the default unless the user explicitly asks for more data. |
| Status | Description |
|---|---|
200 | { tool, result }: the tool's output as JSON |
400 | Invalid arguments (INVALID_ARGUMENTS) |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
429 | Rate limited (per key). Retry-After header set. |
502 | Tool execution failed (TOOL_FAILED) |
curl -X POST https://app.seomatic.ai/api/v1/tools/get_search_queries \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{"days":0,"limit":0}'/tools/get_top_pagesreadGet the top-performing pages from Google Search Console for the connected website. Returns pages ranked by clicks with impressions, CTR, and average position.
| Name | Type | Required | Description |
|---|---|---|---|
days | number | no | Number of days to look back (1-90, default 28) |
limit | number | no | Number of results to return (1-5000, default 50). Use the default unless the user explicitly asks for more data. |
| Status | Description |
|---|---|
200 | { tool, result }: the tool's output as JSON |
400 | Invalid arguments (INVALID_ARGUMENTS) |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
429 | Rate limited (per key). Retry-After header set. |
502 | Tool execution failed (TOOL_FAILED) |
curl -X POST https://app.seomatic.ai/api/v1/tools/get_top_pages \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{"days":0,"limit":0}'/tools/get_dimension_breakdownreadBreak down Google Search Console performance by device (desktop/mobile/tablet), country, or date, optionally filtered to one query or one page. Use for questions like "is mobile underperforming", "wh…
| Name | Type | Required | Description |
|---|---|---|---|
dimension | enum: device | country | date | yes | What to break performance down by |
days | number | no | Number of days to look back (1-90, default 28) |
filterQuery | string | no | Optional: restrict to one exact search query |
filterPage | string | no | Optional: restrict to one exact page URL |
limit | number | no | Max rows (default 50; date returns every day) |
| Status | Description |
|---|---|
200 | { tool, result }: the tool's output as JSON |
400 | Invalid arguments (INVALID_ARGUMENTS) |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
429 | Rate limited (per key). Retry-After header set. |
502 | Tool execution failed (TOOL_FAILED) |
curl -X POST https://app.seomatic.ai/api/v1/tools/get_dimension_breakdown \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{"dimension":"device","days":0,"filterQuery":"…","filterPage":"…","limit":0}'/tools/get_query_page_matrixreadGet the query-to-page map from Google Search Console: which page ranks for which query, with clicks, impressions, and position per pair. THE tool for cannibalization analysis - a query appearing with…
| Name | Type | Required | Description |
|---|---|---|---|
days | number | no | Number of days to look back (1-90, default 28) |
maxRows | number | no | Max query-page pairs to return (default 2000) |
| Status | Description |
|---|---|
200 | { tool, result }: the tool's output as JSON |
400 | Invalid arguments (INVALID_ARGUMENTS) |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
429 | Rate limited (per key). Retry-After header set. |
502 | Tool execution failed (TOOL_FAILED) |
curl -X POST https://app.seomatic.ai/api/v1/tools/get_query_page_matrix \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{"days":0,"maxRows":0}'/tools/compare_periodsreadCompare Google Search Console performance between the current period and the immediately preceding period of the same length, per query or per page. THE tool for decay and growth detection: returns t…
| Name | Type | Required | Description |
|---|---|---|---|
dimension | enum: query | page | no | Compare by query or by page (default page) |
days | number | no | Window length in days (7-45, default 28). Current window vs the window immediately before it. |
limit | number | no | Rows fetched per period before diffing (default 500) |
| Status | Description |
|---|---|
200 | { tool, result }: the tool's output as JSON |
400 | Invalid arguments (INVALID_ARGUMENTS) |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
429 | Rate limited (per key). Retry-After header set. |
502 | Tool execution failed (TOOL_FAILED) |
curl -X POST https://app.seomatic.ai/api/v1/tools/compare_periods \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{"dimension":"query","days":0,"limit":0}'/tools/get_performance_trendreadGet search performance over time from Google Search Console. Returns daily clicks and impressions data for trend analysis.
| Name | Type | Required | Description |
|---|---|---|---|
days | number | no | Number of days to look back (7-90, default 28) |
| Status | Description |
|---|---|
200 | { tool, result }: the tool's output as JSON |
400 | Invalid arguments (INVALID_ARGUMENTS) |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
429 | Rate limited (per key). Retry-After header set. |
502 | Tool execution failed (TOOL_FAILED) |
curl -X POST https://app.seomatic.ai/api/v1/tools/get_performance_trend \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{"days":0}'/tools/inspect_url_indexingreadCheck if a specific URL is indexed by Google and get detailed indexing diagnostics. Returns the indexing verdict (PASS/FAIL/NEUTRAL), coverage state (e.g. "Submitted and indexed", "Crawled - currentl…
| Name | Type | Required | Description |
|---|---|---|---|
url | string (uri) | yes | The fully-qualified URL to inspect (e.g. https://example.com/my-page) |
| Status | Description |
|---|---|
200 | { tool, result }: the tool's output as JSON |
400 | Invalid arguments (INVALID_ARGUMENTS) |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
429 | Rate limited (per key). Retry-After header set. |
502 | Tool execution failed (TOOL_FAILED) |
curl -X POST https://app.seomatic.ai/api/v1/tools/inspect_url_indexing \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{"url":"https://example.com"}'/tools/batch_inspect_urlsreadCheck indexing status for multiple URLs at once. Returns a summary for each URL including whether it is indexed, the coverage state, and any issues. Use this when the user wants to check many pages a…
| Name | Type | Required | Description |
|---|---|---|---|
urls | string[] | yes | Array of fully-qualified URLs to inspect (max 50) |
| Status | Description |
|---|---|
200 | { tool, result }: the tool's output as JSON |
400 | Invalid arguments (INVALID_ARGUMENTS) |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
429 | Rate limited (per key). Retry-After header set. |
502 | Tool execution failed (TOOL_FAILED) |
curl -X POST https://app.seomatic.ai/api/v1/tools/batch_inspect_urls \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{"urls":[]}'Metrics, clusters, intent, and trends for keyword research.
/tools/get_keyword_metricsreadGet detailed SEO metrics for specific keywords including search volume, keyword difficulty (0-100), CPC, competition level, and search intent. Use this when the user asks about specific keywords, whe…
| Name | Type | Required | Description |
|---|---|---|---|
keywords | string[] | yes | Keywords to analyze (1-20 keywords) |
location_code | number | no | Location code (default: 2840 for US). Examples: 2826 for UK, 2250 for France, 2276 for Germany. |
language_code | string | no | Language code (default: "en"). Examples: "fr", "de", "es". |
| Status | Description |
|---|---|
200 | { tool, result }: the tool's output as JSON |
400 | Invalid arguments (INVALID_ARGUMENTS) |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
429 | Rate limited (per key). Retry-After header set. |
502 | Tool execution failed (TOOL_FAILED) |
curl -X POST https://app.seomatic.ai/api/v1/tools/get_keyword_metrics \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{"keywords":[],"location_code":0,"language_code":"…"}'/tools/get_keyword_suggestionsreadFind keyword ideas and suggestions from one or more seed keywords. Returns related keywords with search volume, difficulty, CPC, and search intent. IMPORTANT: Pass ALL seed keywords in a single call…
| Name | Type | Required | Description |
|---|---|---|---|
keywords | string[] | yes | Seed keywords to get suggestions for (up to 10 at once) |
limit | number | no | Number of suggestions per keyword (1-100, default 20). Use the default unless the user explicitly asks for more. |
location_code | number | no | Location code (default: 2840 for US). |
language_code | string | no | Language code (default: "en"). |
| Status | Description |
|---|---|
200 | { tool, result }: the tool's output as JSON |
400 | Invalid arguments (INVALID_ARGUMENTS) |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
429 | Rate limited (per key). Retry-After header set. |
502 | Tool execution failed (TOOL_FAILED) |
curl -X POST https://app.seomatic.ai/api/v1/tools/get_keyword_suggestions \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{"keywords":[],"limit":0,"location_code":0,"language_code":"…"}'/tools/compare_keywordsreadCompare Google Trends interest for multiple keywords side by side. Shows relative search interest over time. Useful for deciding which keywords to target.
| Name | Type | Required | Description |
|---|---|---|---|
keywords | string[] | yes | List of keywords to compare (2-5 keywords) |
geo | string | no | Country code to filter by (e.g., "US", "FR"). Leave empty for worldwide. |
| Status | Description |
|---|---|
200 | { tool, result }: the tool's output as JSON |
400 | Invalid arguments (INVALID_ARGUMENTS) |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
429 | Rate limited (per key). Retry-After header set. |
502 | Tool execution failed (TOOL_FAILED) |
curl -X POST https://app.seomatic.ai/api/v1/tools/compare_keywords \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{"keywords":[],"geo":"…"}'/tools/get_keyword_clustersactsThe agent's keyword-cluster map from the workspace's GSC query universe. Each cluster: topic, queries, landing pages, verdict (pillar | cannibalization | gap | covered), impressions.
| Name | Type | Required | Description |
|---|---|---|---|
verdict | enum: pillar | cannibalization | gap | covered | no | Only clusters with this verdict |
limit | integer | no |
| Status | Description |
|---|---|
200 | { tool, result }: the tool's output as JSON |
400 | Invalid arguments (INVALID_ARGUMENTS) |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA) |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
429 | Rate limited (per key). Retry-After header set. |
502 | Tool execution failed (TOOL_FAILED) |
curl -X POST https://app.seomatic.ai/api/v1/tools/get_keyword_clusters \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{"verdict":"pillar","limit":0}'/tools/get_keyword_trendsreadGet Google Trends interest over time data for a keyword. Shows how search interest has changed over the past year. Useful for understanding seasonality and trending topics.
| Name | Type | Required | Description |
|---|---|---|---|
keyword | string | yes | The keyword to check trends for |
geo | string | no | Country code to filter by (e.g., "US", "FR", "GB"). Leave empty for worldwide. |
| Status | Description |
|---|---|
200 | { tool, result }: the tool's output as JSON |
400 | Invalid arguments (INVALID_ARGUMENTS) |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
429 | Rate limited (per key). Retry-After header set. |
502 | Tool execution failed (TOOL_FAILED) |
curl -X POST https://app.seomatic.ai/api/v1/tools/get_keyword_trends \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{"keyword":"…","geo":"…"}'/tools/get_keyword_performancereadGet keyword-level performance from Google Ads including clicks, impressions, cost, conversions, CPC, and quality score. Use this to understand which keywords drive the most value in ads.
| Name | Type | Required | Description |
|---|---|---|---|
days | number | no | Number of days to look back (1-90, default 30) |
limit | number | no | Number of keywords to return (1-100, default 30) |
| Status | Description |
|---|---|
200 | { tool, result }: the tool's output as JSON |
400 | Invalid arguments (INVALID_ARGUMENTS) |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
429 | Rate limited (per key). Retry-After header set. |
502 | Tool execution failed (TOOL_FAILED) |
curl -X POST https://app.seomatic.ai/api/v1/tools/get_keyword_performance \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{"days":0,"limit":0}'Referring domains, anchors, and link velocity.
/tools/get_backlink_summaryreadGet a backlink profile summary for a domain including total backlinks, referring domains, domain rank, spam score, and link type distribution. Use this when the user asks about link-building, netlink…
| Name | Type | Required | Description |
|---|---|---|---|
domain | string | yes | The domain to analyze backlinks for (e.g., "backmarket.com") |
| Status | Description |
|---|---|
200 | { tool, result }: the tool's output as JSON |
400 | Invalid arguments (INVALID_ARGUMENTS) |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
429 | Rate limited (per key). Retry-After header set. |
502 | Tool execution failed (TOOL_FAILED) |
curl -X POST https://app.seomatic.ai/api/v1/tools/get_backlink_summary \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{"domain":"…"}'/tools/get_backlink_anchorsreadGet the anchor-text distribution of a domain’s backlink profile (anchor, backlink count, referring domains per anchor). Use to assess anchor diversity, over-optimization risk (too many exact-match an…
| Name | Type | Required | Description |
|---|---|---|---|
domain | string | yes | The domain to analyze (e.g., "example.com") |
limit | number | no | Max anchors to return (default 25) |
| Status | Description |
|---|---|
200 | { tool, result }: the tool's output as JSON |
400 | Invalid arguments (INVALID_ARGUMENTS) |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
429 | Rate limited (per key). Retry-After header set. |
502 | Tool execution failed (TOOL_FAILED) |
curl -X POST https://app.seomatic.ai/api/v1/tools/get_backlink_anchors \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{"domain":"…","limit":0}'/tools/get_backlink_velocityreadGet monthly new vs lost referring domains for a domain over recent months. Use to judge link-building momentum, detect link decay or a negative-SEO spike, and compare acquisition pace against competi…
| Name | Type | Required | Description |
|---|---|---|---|
domain | string | yes | The domain to analyze (e.g., "example.com") |
months | number | no | How many months back (default 6) |
| Status | Description |
|---|---|
200 | { tool, result }: the tool's output as JSON |
400 | Invalid arguments (INVALID_ARGUMENTS) |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
429 | Rate limited (per key). Retry-After header set. |
502 | Tool execution failed (TOOL_FAILED) |
curl -X POST https://app.seomatic.ai/api/v1/tools/get_backlink_velocity \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{"domain":"…","months":0}'/tools/get_referring_domainsreadList the top referring domains linking to a domain, ordered by domain rank. Use for link-profile analysis, competitor backlink-gap research ("who links to them but not to us"), and finding link sourc…
| Name | Type | Required | Description |
|---|---|---|---|
domain | string | yes | The domain to analyze (e.g., "competitor.com") |
limit | number | no | Max referring domains to return (default 50) |
| Status | Description |
|---|---|
200 | { tool, result }: the tool's output as JSON |
400 | Invalid arguments (INVALID_ARGUMENTS) |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
429 | Rate limited (per key). Retry-After header set. |
502 | Tool execution failed (TOOL_FAILED) |
curl -X POST https://app.seomatic.ai/api/v1/tools/get_referring_domains \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{"domain":"…","limit":0}'SERP features, rankings, and domain-level competitive data.
/tools/get_serp_featuresreadSee which SERP features (AI Overview, featured snippet, People Also Ask, local pack, video, shopping, etc.) appear on the Google results page for up to 10 keywords. Use to judge how much organic room…
| Name | Type | Required | Description |
|---|---|---|---|
keywords | string[] | yes | Keywords to inspect (1-10) |
| Status | Description |
|---|---|
200 | { tool, result }: the tool's output as JSON |
400 | Invalid arguments (INVALID_ARGUMENTS) |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
429 | Rate limited (per key). Retry-After header set. |
502 | Tool execution failed (TOOL_FAILED) |
curl -X POST https://app.seomatic.ai/api/v1/tools/get_serp_features \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{"keywords":[]}'/tools/get_domain_rankingsreadGet the top keywords a domain ranks for in Google search results. Returns keywords with search volume, difficulty, and ranking data. Use this when the user asks about a site's SEO performance, best r…
| Name | Type | Required | Description |
|---|---|---|---|
domain | string | yes | The domain to analyze (e.g., "backmarket.com") |
limit | number | no | Number of keywords to return (1-100, default 30) |
location_code | number | no | Location code (default: 2840 for US). |
language_code | string | no | Language code (default: "en"). |
| Status | Description |
|---|---|
200 | { tool, result }: the tool's output as JSON |
400 | Invalid arguments (INVALID_ARGUMENTS) |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
429 | Rate limited (per key). Retry-After header set. |
502 | Tool execution failed (TOOL_FAILED) |
curl -X POST https://app.seomatic.ai/api/v1/tools/get_domain_rankings \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{"domain":"…","limit":0,"location_code":0,"language_code":"…"}'/tools/get_domain_overviewreadGet an overview of a domain's SEO visibility including organic ranking distribution (how many keywords in top 1, top 3, top 10, etc.), estimated traffic volume, and estimated traffic cost. Use this f…
| Name | Type | Required | Description |
|---|---|---|---|
domain | string | yes | The domain to analyze (e.g., "backmarket.com") |
location_code | number | no | Location code (default: 2840 for US). |
language_code | string | no | Language code (default: "en"). |
| Status | Description |
|---|---|
200 | { tool, result }: the tool's output as JSON |
400 | Invalid arguments (INVALID_ARGUMENTS) |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
429 | Rate limited (per key). Retry-After header set. |
502 | Tool execution failed (TOOL_FAILED) |
curl -X POST https://app.seomatic.ai/api/v1/tools/get_domain_overview \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{"domain":"…","location_code":0,"language_code":"…"}'/tools/get_domain_competitorsreadFind competing domains in organic search results. Shows domains that rank for similar keywords with keyword intersection counts, average positions, and estimated traffic. Use this when the user asks…
| Name | Type | Required | Description |
|---|---|---|---|
domain | string | yes | The domain to find competitors for (e.g., "backmarket.com") |
limit | number | no | Number of competitors to return (1-50, default 20) |
location_code | number | no | Location code (default: 2840 for US). |
language_code | string | no | Language code (default: "en"). |
| Status | Description |
|---|---|
200 | { tool, result }: the tool's output as JSON |
400 | Invalid arguments (INVALID_ARGUMENTS) |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
429 | Rate limited (per key). Retry-After header set. |
502 | Tool execution failed (TOOL_FAILED) |
curl -X POST https://app.seomatic.ai/api/v1/tools/get_domain_competitors \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{"domain":"…","limit":0,"location_code":0,"language_code":"…"}'Google Analytics traffic and Google Ads campaigns.
/tools/get_traffic_overviewreadGet a traffic overview from Google Analytics (GA4): total sessions, users, page views, bounce rate, average session duration, and new users. Use this for a high-level understanding of website traffic.
| Name | Type | Required | Description |
|---|---|---|---|
days | number | no | Number of days to look back (1-90, default 28) |
| Status | Description |
|---|---|
200 | { tool, result }: the tool's output as JSON |
400 | Invalid arguments (INVALID_ARGUMENTS) |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
429 | Rate limited (per key). Retry-After header set. |
502 | Tool execution failed (TOOL_FAILED) |
curl -X POST https://app.seomatic.ai/api/v1/tools/get_traffic_overview \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{"days":0}'/tools/get_traffic_sourcesreadGet traffic source breakdown from Google Analytics (GA4): sessions by channel (Organic Search, Direct, Referral, Social, Paid Search, etc.) with users, bounce rate, and conversions. Essential for und…
| Name | Type | Required | Description |
|---|---|---|---|
days | number | no | Number of days to look back (1-90, default 28) |
| Status | Description |
|---|---|
200 | { tool, result }: the tool's output as JSON |
400 | Invalid arguments (INVALID_ARGUMENTS) |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
429 | Rate limited (per key). Retry-After header set. |
502 | Tool execution failed (TOOL_FAILED) |
curl -X POST https://app.seomatic.ai/api/v1/tools/get_traffic_sources \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{"days":0}'/tools/get_landing_pagesreadGet the top landing pages (entry pages) from Google Analytics (GA4) with sessions, users, bounce rate, and conversions. These are the first pages visitors see: critical for SEO analysis.
| Name | Type | Required | Description |
|---|---|---|---|
days | number | no | Number of days to look back (1-90, default 28) |
limit | number | no | Number of landing pages to return (1-100, default 25) |
| Status | Description |
|---|---|
200 | { tool, result }: the tool's output as JSON |
400 | Invalid arguments (INVALID_ARGUMENTS) |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
429 | Rate limited (per key). Retry-After header set. |
502 | Tool execution failed (TOOL_FAILED) |
curl -X POST https://app.seomatic.ai/api/v1/tools/get_landing_pages \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{"days":0,"limit":0}'/tools/get_top_viewed_pagesreadGet the most viewed pages from Google Analytics (GA4) with page views, sessions, bounce rate, and average time on page. Use this to identify top-performing content.
| Name | Type | Required | Description |
|---|---|---|---|
days | number | no | Number of days to look back (1-90, default 28) |
limit | number | no | Number of pages to return (1-100, default 25) |
| Status | Description |
|---|---|
200 | { tool, result }: the tool's output as JSON |
400 | Invalid arguments (INVALID_ARGUMENTS) |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
429 | Rate limited (per key). Retry-After header set. |
502 | Tool execution failed (TOOL_FAILED) |
curl -X POST https://app.seomatic.ai/api/v1/tools/get_top_viewed_pages \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{"days":0,"limit":0}'/tools/get_account_overviewreadGet a high-level overview of Google Ads account performance: total spend, clicks, impressions, conversions, average CTR, average CPC, and number of active campaigns.
| Name | Type | Required | Description |
|---|---|---|---|
days | number | no | Number of days to look back (1-90, default 30) |
| Status | Description |
|---|---|
200 | { tool, result }: the tool's output as JSON |
400 | Invalid arguments (INVALID_ARGUMENTS) |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
429 | Rate limited (per key). Retry-After header set. |
502 | Tool execution failed (TOOL_FAILED) |
curl -X POST https://app.seomatic.ai/api/v1/tools/get_account_overview \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{"days":0}'/tools/get_ad_campaignsreadGet Google Ads campaign performance data including clicks, impressions, cost, conversions, CTR, and average CPC. Use this to understand which ad campaigns are performing well.
| Name | Type | Required | Description |
|---|---|---|---|
days | number | no | Number of days to look back (1-90, default 30) |
limit | number | no | Number of campaigns to return (1-50, default 20) |
| Status | Description |
|---|---|
200 | { tool, result }: the tool's output as JSON |
400 | Invalid arguments (INVALID_ARGUMENTS) |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
429 | Rate limited (per key). Retry-After header set. |
502 | Tool execution failed (TOOL_FAILED) |
curl -X POST https://app.seomatic.ai/api/v1/tools/get_ad_campaigns \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{"days":0,"limit":0}'/tools/get_search_termsreadGet actual search terms that triggered Google Ads. This is extremely valuable for SEO: it shows real queries people type that lead to clicks. Use this for keyword discovery, content ideas, and unders…
| Name | Type | Required | Description |
|---|---|---|---|
days | number | no | Number of days to look back (1-90, default 30) |
limit | number | no | Number of search terms to return (1-100, default 50) |
| Status | Description |
|---|---|
200 | { tool, result }: the tool's output as JSON |
400 | Invalid arguments (INVALID_ARGUMENTS) |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
429 | Rate limited (per key). Retry-After header set. |
502 | Tool execution failed (TOOL_FAILED) |
curl -X POST https://app.seomatic.ai/api/v1/tools/get_search_terms \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{"days":0,"limit":0}'Google Business Profile locations, visibility, and reviews.
/tools/list_business_locationsreadList the Google Business Profile locations on the connected account, with each location’s title, primary category, website, and full NAP (name, address, phone). Use for local SEO: verifying NAP consi…
| Status | Description |
|---|---|
200 | { tool, result }: the tool's output as JSON |
400 | Invalid arguments (INVALID_ARGUMENTS) |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
429 | Rate limited (per key). Retry-After header set. |
502 | Tool execution failed (TOOL_FAILED) |
curl -X POST https://app.seomatic.ai/api/v1/tools/list_business_locations \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{}'/tools/get_local_visibilityreadMeasure a site's LOCAL search visibility for specific money keywords: its organic positions, whether Google shows a local (map) pack and who occupies it, which directories (Psychology Today, Yelp, Zo…
| Name | Type | Required | Description |
|---|---|---|---|
keywords | string[] | yes | Geo-modified money keywords to measure (1-5). Include the city/area the business serves. |
location_name | string | no | City-level SERP location as a DataForSEO canonical name: "City,Region,Country" with full names, no abbreviations (e.g.… |
location_code | number | no | Location code override (defaults to the workspace market). Ignored when location_name is set. |
language_code | string | no | Language code override (defaults to the workspace market). |
| Status | Description |
|---|---|
200 | { tool, result }: the tool's output as JSON |
400 | Invalid arguments (INVALID_ARGUMENTS) |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
429 | Rate limited (per key). Retry-After header set. |
502 | Tool execution failed (TOOL_FAILED) |
curl -X POST https://app.seomatic.ai/api/v1/tools/get_local_visibility \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{"keywords":[],"location_name":"…","location_code":0,"language_code":"…"}'/tools/get_business_reviewsreadGet the average star rating and total review count for one Google Business Profile location. Pass the location resource name from list_business_locations (e.g. "locations/12345"). Use to track reputa…
| Name | Type | Required | Description |
|---|---|---|---|
location | string | yes | The location resource name from list_business_locations, e.g. "locations/12345" |
| Status | Description |
|---|---|
200 | { tool, result }: the tool's output as JSON |
400 | Invalid arguments (INVALID_ARGUMENTS) |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
429 | Rate limited (per key). Retry-After header set. |
502 | Tool execution failed (TOOL_FAILED) |
curl -X POST https://app.seomatic.ai/api/v1/tools/get_business_reviews \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{"location":"…"}'The agent's own work: diagnosis, tasks, and strategy.
/tools/get_seo_snapshotactsCompact brief of the SEO agent's cached signals for this workspace (site inventory, GSC performance, GEO gaps, content scores, open questions). Read this before proposing SEO work.
| Status | Description |
|---|---|
200 | { tool, result }: the tool's output as JSON |
400 | Invalid arguments (INVALID_ARGUMENTS) |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA) |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
429 | Rate limited (per key). Retry-After header set. |
502 | Tool execution failed (TOOL_FAILED) |
curl -X POST https://app.seomatic.ai/api/v1/tools/get_seo_snapshot \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{}'/tools/get_seo_strategyactsThe agent's current SEO strategy for this workspace: strategic themes, ranked big plays, rationale, baseline metrics, freshness. Read it before discussing priorities or proposing new work.
| Status | Description |
|---|---|
200 | { tool, result }: the tool's output as JSON |
400 | Invalid arguments (INVALID_ARGUMENTS) |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA) |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
429 | Rate limited (per key). Retry-After header set. |
502 | Tool execution failed (TOOL_FAILED) |
curl -X POST https://app.seomatic.ai/api/v1/tools/get_seo_strategy \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{}'/tools/get_seo_signalactsRead ONE cached agent signal in full (compacted): the same raw data the weekly diagnosis reasons over, beyond the digest's summary. FREE: reads the cache only, never gathers, never spends credits. Us…
| Name | Type | Required | Description |
|---|---|---|---|
signal | enum: sitemap | content_inventory | gsc_performance | geo_gaps | content_scores | pagespeed | keyword_metrics | link_graph | keyword_gaps | index_coverage | brand_mentions | conversion_data | conversion_impact | local_presence | local_visibility | citation_audit | link_equity | serp_snapshot | serp_displacements | ai_surface | topic_trends | true_keyword_gaps | ai_referrals | reddit_topics | ads_performance | page_audit | bootstrap_keywords | backlink_profile | score_calibration | skill_effectiveness | chat_initiative | yes | Which cached signal to read |
| Status | Description |
|---|---|
200 | { tool, result }: the tool's output as JSON |
400 | Invalid arguments (INVALID_ARGUMENTS) |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA) |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
429 | Rate limited (per key). Retry-After header set. |
502 | Tool execution failed (TOOL_FAILED) |
curl -X POST https://app.seomatic.ai/api/v1/tools/get_seo_signal \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{"signal":"sitemap"}'/tools/get_content_scoresactsAI-search content scores for the workspace's generated articles: average score plus the weakest items (improvement candidates).
| Name | Type | Required | Description |
|---|---|---|---|
limit | integer | no |
| Status | Description |
|---|---|
200 | { tool, result }: the tool's output as JSON |
400 | Invalid arguments (INVALID_ARGUMENTS) |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA) |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
429 | Rate limited (per key). Retry-After header set. |
502 | Tool execution failed (TOOL_FAILED) |
curl -X POST https://app.seomatic.ai/api/v1/tools/get_content_scores \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{"limit":0}'/tools/list_seo_tasksactsThe agent's SEO tasks for this workspace (the plan board). Filter by status or type. Statuses: proposed (awaiting approval), approved, in_progress, verifying (maturing), verified/ineffective/regresse…
| Name | Type | Required | Description |
|---|---|---|---|
status | enum: proposed | approved | in_progress | verifying | verified | ineffective | regressed | inconclusive | done | dismissed | obsolete | no | |
type | string | no | Task type, e.g. ctr_fix |
limit | integer | no |
| Status | Description |
|---|---|
200 | { tool, result }: the tool's output as JSON |
400 | Invalid arguments (INVALID_ARGUMENTS) |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA) |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
429 | Rate limited (per key). Retry-After header set. |
502 | Tool execution failed (TOOL_FAILED) |
curl -X POST https://app.seomatic.ai/api/v1/tools/list_seo_tasks \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{"status":"proposed","type":"…","limit":0}'/tools/get_seo_taskactsFull detail + execution history of one agent task: rationale, impact estimate, evidence, dependencies, and the latest execution actions. Also the way to check whether an executed task finished.
| Name | Type | Required | Description |
|---|---|---|---|
taskId | string (uuid) | yes | The task id |
| Status | Description |
|---|---|
200 | { tool, result }: the tool's output as JSON |
400 | Invalid arguments (INVALID_ARGUMENTS) |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA) |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
429 | Rate limited (per key). Retry-After header set. |
502 | Tool execution failed (TOOL_FAILED) |
curl -X POST https://app.seomatic.ai/api/v1/tools/get_seo_task \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{"taskId":"00000000-0000-0000-0000-000000000000"}'/tools/load_skillactsLoad ONE SEO specialist's full playbook (the workspace's configured methodology for that domain) so you can apply its real guidance instead of general knowledge. The 'Available specialists' summaries…
| Name | Type | Required | Description |
|---|---|---|---|
slug | string | yes | The specialist's slug, e.g. 'technical-seo', 'geo', 'international-seo'. Must match one of the Available specialists li… |
| Status | Description |
|---|---|
200 | { tool, result }: the tool's output as JSON |
400 | Invalid arguments (INVALID_ARGUMENTS) |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA) |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
429 | Rate limited (per key). Retry-After header set. |
502 | Tool execution failed (TOOL_FAILED) |
curl -X POST https://app.seomatic.ai/api/v1/tools/load_skill \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{"slug":"…"}'/tools/create_seo_tasksactsStage up to 5 SEO tasks in the agent's plan as PROPOSALS. This NEVER executes anything: each staged task renders a card where the user approves and optionally runs it through the agent's gated pipeli…
| Name | Type | Required | Description |
|---|---|---|---|
tasks | object[] | yes | |
campaign | object | no | OPTIONAL. Pass this when the user asked for a CAMPAIGN or a multi-step initiative (e.g. via the "Start a campaign" butt… |
| Status | Description |
|---|---|
200 | { tool, result }: the tool's output as JSON |
400 | Invalid arguments (INVALID_ARGUMENTS) |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA) |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
429 | Rate limited (per key). Retry-After header set. |
502 | Tool execution failed (TOOL_FAILED) |
curl -X POST https://app.seomatic.ai/api/v1/tools/create_seo_tasks \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{"tasks":[],"campaign":{}}'/tools/claim_seo_taskacts"Leave that to me": the user takes OVER a task the agent planned (found via list_seo_tasks). The agent's task is withdrawn with a claimed-by-user marker so the agent never duplicates it and the plan…
| Name | Type | Required | Description |
|---|---|---|---|
taskId | string | yes | The task id (from list_seo_tasks) |
| Status | Description |
|---|---|
200 | { tool, result }: the tool's output as JSON |
400 | Invalid arguments (INVALID_ARGUMENTS) |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA) |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
429 | Rate limited (per key). Retry-After header set. |
502 | Tool execution failed (TOOL_FAILED) |
curl -X POST https://app.seomatic.ai/api/v1/tools/claim_seo_task \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{"taskId":"…"}'Bulk page programs, content sweeps, and blog authoring.
/tools/list_seo_campaignsactsThe agent's campaigns (coordinated multi-task initiatives) with status, per-status task counts, and: for bulk_edit/page_scale campaigns: the bulk state: wave progress, auto-pause reason (circuit brea…
| Name | Type | Required | Description |
|---|---|---|---|
status | enum: proposed | approved | active | paused | done | abandoned | no |
| Status | Description |
|---|---|
200 | { tool, result }: the tool's output as JSON |
400 | Invalid arguments (INVALID_ARGUMENTS) |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA) |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
429 | Rate limited (per key). Retry-After header set. |
502 | Tool execution failed (TOOL_FAILED) |
curl -X POST https://app.seomatic.ai/api/v1/tools/list_seo_campaigns \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{"status":"proposed"}'/tools/manage_campaignactsPause, resume, update the brief of, or abandon one of the agent's campaigns ON THE USER'S BEHALF: never send the user to the dashboard for these. pause: holds execution, tasks keep their status. resu…
| Name | Type | Required | Description |
|---|---|---|---|
campaignId | string (uuid) | yes | |
action | enum: pause | resume | abandon | update_brief | yes | |
confirm | boolean | no | Required true for abandon: attests the user explicitly asked for this irreversible action. |
brief | string | no | update_brief only: the FULL replacement brief the template will be re-authored from. Enrich with concrete substance (se… |
| Status | Description |
|---|---|
200 | { tool, result }: the tool's output as JSON |
400 | Invalid arguments (INVALID_ARGUMENTS) |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA) |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
429 | Rate limited (per key). Retry-After header set. |
502 | Tool execution failed (TOOL_FAILED) |
curl -X POST https://app.seomatic.ai/api/v1/tools/manage_campaign \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{"campaignId":"00000000-0000-0000-0000-000000000000","action":"pause","confirm":true,"brief":"…"}'/tools/propose_page_scale_campaignactsStage a landing-pages-AT-SCALE campaign (programmatic SEO: e.g. "a page for each of the 50 US states", "X vs Y comparison pages"): up to 500 pages generated from ONE agent-authored template + a datas…
| Name | Type | Required | Description |
|---|---|---|---|
title | string | yes | |
kind | string | yes | What kind of pages, e.g. "location pages", "comparison pages", "use-case pages" |
brief | string | yes | The full brief the template author follows: audience, search intent, what each page must contain, tone |
rowSourceKind | enum: ai | user | library | gbp_locations | yes | |
rowPrompt | string | no | rowSourceKind=ai: what dataset to generate (e.g. 'the 50 US states with population, largest city, region') |
rows | object[] | no | rowSourceKind=user: the rows, one object per page (keys become dataset columns) |
libraryDatasetId | string | no | rowSourceKind=library: the dataset id to attach |
rowTarget | integer | no | |
allowGenText | boolean | no | Allow up to 2 per-row AI text badges in the template (costs credits per page; default false = pure variables, 0 credits) |
publishAsDraft | boolean | no | |
pageTemplate | string | no | A BUILT-IN template id from list_page_templates ('comparison', 'location'). Its section design, structured data and int… |
| Status | Description |
|---|---|
200 | { tool, result }: the tool's output as JSON |
400 | Invalid arguments (INVALID_ARGUMENTS) |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA) |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
429 | Rate limited (per key). Retry-After header set. |
502 | Tool execution failed (TOOL_FAILED) |
curl -X POST https://app.seomatic.ai/api/v1/tools/propose_page_scale_campaign \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{"title":"…","kind":"…","brief":"…","rowSourceKind":"ai","rowPrompt":"…","rows":[],"libraryDatasetId":"…","rowTarget":0,"allowGenText":true,"publishAsDraft":true,"pageTemplate":"…"}'/tools/propose_content_sweep_campaignactsStage a CONTENT SWEEP as a managed CAMPAIGN: N DISTINCT blog articles on N different topics, tracked on the agent board with a planning phase. Up to 50 topics, batched into ONE run of the blog pipeli…
| Name | Type | Required | Description |
|---|---|---|---|
title | string | yes | |
topics | string[] | yes | One article per topic. Make them genuinely DISTINCT subjects: near-duplicate topics cannibalize each other, and the pla… |
brief | string | no | Editorial direction shared by every article: audience, angle, tone, what each piece must do. |
| Status | Description |
|---|---|
200 | { tool, result }: the tool's output as JSON |
400 | Invalid arguments (INVALID_ARGUMENTS) |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA) |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
429 | Rate limited (per key). Retry-After header set. |
502 | Tool execution failed (TOOL_FAILED) |
curl -X POST https://app.seomatic.ai/api/v1/tools/propose_content_sweep_campaign \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{"title":"…","topics":[],"brief":"…"}'/tools/create_bulk_edit_campaignactsStage ONE bulk sweep campaign that applies an instruction across MANY pages (e.g. "rewrite every meta title to include the current year", "add alt text to all images sitewide"): up to 500 pages, one…
| Name | Type | Required | Description |
|---|---|---|---|
taskType | enum: ctr_fix | striking_distance | og_tags | alt_text | freshness_stamp | heading_fix | faq_block | schema_repair | schema | content_refresh | eeat_enrichment | broken_link_fix | geo_enrichment | author_schema | internal_links | index_request | cwv_fix | yes | What the sweep rewrites on every page |
instruction | string | no | The shared brief every page rewrite follows (required unless segments[] is provided): be specific |
title | string | no | |
selectorKind | enum: urls | path_prefix | all_pages | no | Single-segment sweeps: how to pick the pages: an explicit URL list, every inventory page under a path prefix, or the wh… |
urls | string[] | no | Required when selectorKind=urls |
pathPrefix | string | no | Required when selectorKind=path_prefix, e.g. /blog |
segments | object[] | no | Mixed-template sweeps: per-section selector + instruction (overrides selectorKind/instruction) |
maxPages | integer | no |
| Status | Description |
|---|---|
200 | { tool, result }: the tool's output as JSON |
400 | Invalid arguments (INVALID_ARGUMENTS) |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA) |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
429 | Rate limited (per key). Retry-After header set. |
502 | Tool execution failed (TOOL_FAILED) |
curl -X POST https://app.seomatic.ai/api/v1/tools/create_bulk_edit_campaign \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{"taskType":"ctr_fix","instruction":"…","title":"…","selectorKind":"urls","urls":[],"pathPrefix":"…","segments":[],"maxPages":0}'/tools/write_blog_articlesactsThe DIRECT path for "write N blog articles": validates FIRST, then stages ONE approval card in this chat. Use this by DEFAULT when the user asks for multiple articles (2-50 topics): it is the fast, s…
| Name | Type | Required | Description |
|---|---|---|---|
topics | string[] | yes | One article per topic. Make them genuinely DISTINCT subjects: near-duplicates are collapsed by validation anyway. |
autoPublish | boolean | no | Default FALSE: every article stages as a draft for the user to read and publish themselves: net-new content carries the… |
| Status | Description |
|---|---|
200 | { tool, result }: the tool's output as JSON |
400 | Invalid arguments (INVALID_ARGUMENTS) |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA) |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
429 | Rate limited (per key). Retry-After header set. |
502 | Tool execution failed (TOOL_FAILED) |
curl -X POST https://app.seomatic.ai/api/v1/tools/write_blog_articles \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{"topics":[],"autoPublish":true}'/tools/save_blog_articlereadSave an article you drafted IN this conversation so the user can publish it with one click. ONLY for inline drafting: when the user explicitly wants to read/iterate on the draft here in chat. For "wr…
| Name | Type | Required | Description |
|---|---|---|---|
title | string | yes | The blog article title |
content | string | yes | The full blog article content in Markdown format. |
slug | string | yes | URL slug for the article (e.g., "best-seo-tools-2025"). Lowercase with hyphens. |
excerpt | string | yes | A short summary/excerpt of the article (1-2 sentences). |
metaTitle | string | no | SEO meta title. Defaults to the article title. |
metaDescription | string | no | SEO meta description. Defaults to the excerpt. |
featuredImagePrompt | string | yes | A descriptive prompt for AI image generation to create the featured image. |
| Status | Description |
|---|---|
200 | { tool, result }: the tool's output as JSON |
400 | Invalid arguments (INVALID_ARGUMENTS) |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
429 | Rate limited (per key). Retry-After header set. |
502 | Tool execution failed (TOOL_FAILED) |
curl -X POST https://app.seomatic.ai/api/v1/tools/save_blog_article \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{"title":"…","content":"…","slug":"…","excerpt":"…","metaTitle":"…","metaDescription":"…","featuredImagePrompt":"…"}'The library that powers programmatic pages.
/tools/list_datasetsreadThe structured datasets available for programmatic pages: the curated public library (real, sourced, CC0 data) plus datasets this user created or forked. Returns each dataset's id, name, column names…
| Name | Type | Required | Description |
|---|---|---|---|
search | string | no | Filter by name/description, e.g. "cities", "comparison", "services" |
category | string | no | Filter by category, e.g. locations, software, health, restaurants, jobs |
| Status | Description |
|---|---|
200 | { tool, result }: the tool's output as JSON |
400 | Invalid arguments (INVALID_ARGUMENTS) |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
429 | Rate limited (per key). Retry-After header set. |
502 | Tool execution failed (TOOL_FAILED) |
curl -X POST https://app.seomatic.ai/api/v1/tools/list_datasets \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{"search":"…","category":"…"}'/tools/get_dataset_rowsreadRead a sample of rows from a dataset, to see what the data actually looks like before using it. Returns the columns and up to 25 rows. Get the id from list_datasets first.
| Name | Type | Required | Description |
|---|---|---|---|
datasetId | string | yes | The dataset id from list_datasets |
limit | integer | no | How many rows to sample (default 5) |
| Status | Description |
|---|---|
200 | { tool, result }: the tool's output as JSON |
400 | Invalid arguments (INVALID_ARGUMENTS) |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
429 | Rate limited (per key). Retry-After header set. |
502 | Tool execution failed (TOOL_FAILED) |
curl -X POST https://app.seomatic.ai/api/v1/tools/get_dataset_rows \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{"datasetId":"…","limit":0}'/tools/list_page_templatesreadThe built-in page templates for programmatic SEO. Each has a hand-built section design, code-generated structured data and a code-computed internal-link graph: strictly better than an AI-authored {{v…
| Status | Description |
|---|---|
200 | { tool, result }: the tool's output as JSON |
400 | Invalid arguments (INVALID_ARGUMENTS) |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
429 | Rate limited (per key). Retry-After header set. |
502 | Tool execution failed (TOOL_FAILED) |
curl -X POST https://app.seomatic.ai/api/v1/tools/list_page_templates \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{}'/tools/get_page_templatereadThe full details of one built-in page template: its sections, the dataset columns it requires, its example dataset, and its AI cost per page. Get the id from list_page_templates first.
| Name | Type | Required | Description |
|---|---|---|---|
templateId | string | yes | The template id from list_page_templates |
| Status | Description |
|---|---|
200 | { tool, result }: the tool's output as JSON |
400 | Invalid arguments (INVALID_ARGUMENTS) |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
429 | Rate limited (per key). Retry-After header set. |
502 | Tool execution failed (TOOL_FAILED) |
curl -X POST https://app.seomatic.ai/api/v1/tools/get_page_template \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{"templateId":"…"}'Crawl, analyze, and inventory the site itself.
/tools/analyze_page_seoreadAnalyze a webpage for SEO issues and return an SEO score (0-100) along with a list of critical, warning, and informational issues. Checks title, meta description, headings, content length, images, li…
| Name | Type | Required | Description |
|---|---|---|---|
url | string (uri) | yes | The full URL of the page to analyze |
| Status | Description |
|---|---|
200 | { tool, result }: the tool's output as JSON |
400 | Invalid arguments (INVALID_ARGUMENTS) |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
429 | Rate limited (per key). Retry-After header set. |
502 | Tool execution failed (TOOL_FAILED) |
curl -X POST https://app.seomatic.ai/api/v1/tools/analyze_page_seo \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{"url":"https://example.com"}'/tools/crawl_pagereadCrawl a webpage and extract its SEO metadata including title, meta description, headings, word count, links, images, schema markup, and Open Graph tags. Use this to analyze any public URL.
| Name | Type | Required | Description |
|---|---|---|---|
url | string (uri) | yes | The full URL of the page to crawl (must be https:// or http://) |
| Status | Description |
|---|---|
200 | { tool, result }: the tool's output as JSON |
400 | Invalid arguments (INVALID_ARGUMENTS) |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
429 | Rate limited (per key). Retry-After header set. |
502 | Tool execution failed (TOOL_FAILED) |
curl -X POST https://app.seomatic.ai/api/v1/tools/crawl_page \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{"url":"https://example.com"}'/tools/get_site_inventoryactsPages of the user's REAL site as synced from their CMS/crawl (title, meta, word count, structure). Filter by URL/title substring. Paginated.
| Name | Type | Required | Description |
|---|---|---|---|
query | string | no | Substring to match against page URL or title |
limit | integer | no | |
offset | integer | no |
| Status | Description |
|---|---|
200 | { tool, result }: the tool's output as JSON |
400 | Invalid arguments (INVALID_ARGUMENTS) |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA) |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
429 | Rate limited (per key). Retry-After header set. |
502 | Tool execution failed (TOOL_FAILED) |
curl -X POST https://app.seomatic.ai/api/v1/tools/get_site_inventory \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{"query":"…","limit":0,"offset":0}'Register and manage outbound webhook endpoints (Infrastructure).
/webhooksList this workspace's webhook endpoints (signing secret masked).
| Status | Description |
|---|---|
200 | Endpoints + the available event names |
401 | Missing or invalid API key |
402 | Webhooks require the Infrastructure plan |
429 | Rate limited (per key). Retry-After header set. |
curl -X GET https://app.seomatic.ai/api/v1/webhooks \ -H "Authorization: Bearer smk_live_..."
/webhooksRegister a webhook endpoint. The signing secret is returned IN FULL exactly once.
| Name | Type | Required | Description |
|---|---|---|---|
url | string (uri) | yes | https endpoint to receive signed POSTs. |
events | string[] | no | Subscribed events. Empty = all events. |
| Status | Description |
|---|---|
201 | The endpoint + its full signing secret |
400 | Invalid or non-public URL (SSRF-rejected) |
401 | Missing or invalid API key |
402 | Webhooks require the Infrastructure plan |
409 | Per-workspace endpoint cap reached |
429 | Rate limited (per key). Retry-After header set. |
curl -X POST https://app.seomatic.ai/api/v1/webhooks \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{"url":"https://example.com/hook","events":[]}'/webhooks/{webhookId}Enable/disable an endpoint or change its subscribed events.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
webhookId | path | string (uuid) | yes |
| Name | Type | Required | Description |
|---|---|---|---|
enabled | boolean | no | |
events | string[] | no |
| Status | Description |
|---|---|
200 | The updated endpoint |
401 | Missing or invalid API key |
402 | Webhooks require the Infrastructure plan |
404 | No such endpoint in this workspace |
429 | Rate limited (per key). Retry-After header set. |
curl -X PATCH https://app.seomatic.ai/api/v1/webhooks/{webhookId} \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{"enabled":true,"events":[]}'/webhooks/{webhookId}Remove a webhook endpoint.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
webhookId | path | string (uuid) | yes |
| Status | Description |
|---|---|
200 | Deleted |
401 | Missing or invalid API key |
402 | Webhooks require the Infrastructure plan |
404 | No such endpoint in this workspace |
429 | Rate limited (per key). Retry-After header set. |
curl -X DELETE https://app.seomatic.ai/api/v1/webhooks/{webhookId} \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{}'Triggers (Scale+) and actions (Infrastructure) for no-code Zaps.
/zapier/meZapier connection test: verifies the key and Scale-plan access.
| Status | Description |
|---|---|
200 | Workspace label + scopes |
401 | Missing or invalid API key |
402 | Plan does not include Zapier (Scale+) |
429 | Rate limited (per key). Retry-After header set. |
curl -X GET https://app.seomatic.ai/api/v1/zapier/me \ -H "Authorization: Bearer smk_live_..."
/zapier/subscribeRegister a Zapier REST-hook for an event (page.published, task.completed, ai_visibility.scan_completed).
| Name | Type | Required | Description |
|---|---|---|---|
targetUrl | string (uri) | yes | Zapier's hook catcher URL (https). |
event | enum: page.published | page.publish_failed | task.completed | campaign.completed | ai_visibility.scan_completed | yes | The event to fire the Zap on. |
| Status | Description |
|---|---|
201 | Subscription id (pass to unsubscribe) |
401 | Missing or invalid API key |
402 | Plan does not include Zapier (Scale+) |
429 | Rate limited (per key). Retry-After header set. |
curl -X POST https://app.seomatic.ai/api/v1/zapier/subscribe \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{"targetUrl":"https://example.com/hook","event":"page.published"}'/zapier/unsubscribeRemove a Zapier REST-hook by its subscription id.
| Name | Type | Required | Description |
|---|---|---|---|
id | string (uuid) | yes | The subscription id returned by /subscribe. |
| Status | Description |
|---|---|
200 | Deleted |
401 | Missing or invalid API key |
402 | Plan does not include Zapier (Scale+) |
429 | Rate limited (per key). Retry-After header set. |
curl -X POST https://app.seomatic.ai/api/v1/zapier/unsubscribe \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{"id":"00000000-0000-0000-0000-000000000000"}'/zapier/triggers/published-pagesPolling trigger and sample data: recently published pages, newest first.
| Status | Description |
|---|---|
200 | Array of published pages with stable ids |
401 | Missing or invalid API key |
402 | Plan does not include Zapier (Scale+) |
429 | Rate limited (per key). Retry-After header set. |
curl -X GET https://app.seomatic.ai/api/v1/zapier/triggers/published-pages \ -H "Authorization: Bearer smk_live_..."
/zapier/actions/submit-urlAction: submit a URL for instant indexing (Google + IndexMeNow). Requires Infrastructure (acting over REST).
| Name | Type | Required | Description |
|---|---|---|---|
url | string (uri) | yes | The http(s) URL to submit for indexing. |
| Status | Description |
|---|---|
200 | Per-channel submission result |
401 | Missing or invalid API key |
402 | Acting over REST requires Infrastructure, or plan lacks Zapier |
429 | Rate limited (per key). Retry-After header set. |
curl -X POST https://app.seomatic.ai/api/v1/zapier/actions/submit-url \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{"url":"https://example.com/hook"}'