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. Most endpoints allow up to 500 requests per minute; tool invocations (POST /tools/{name}) have their own tighter budget of 60 calls per minute and 1,000 per hour, the same meter the MCP server uses. 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_..."
One natural-language question, answered with this key's own tool roster - the non-streaming sibling of chat.
/askAsk one natural-language question, answered with this key's own tool roster.
| Name | Type | Required | Description |
|---|---|---|---|
question | string | yes | The question, in plain language. |
client | string | no | Surface attribution (e.g. wp-plugin, n8n, cli), so questions are not all attributed to curl. |
| Status | Description |
|---|---|
200 | The answer, with the tools it used |
400 | Missing or invalid question |
402 | Monthly question quota exhausted |
curl -X POST https://app.seomatic.ai/api/v1/ask \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{"question":"…","client":"…"}'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/decaying-pagesPages that LOST clicks: the recent window vs the adjacent window before it.
| 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 | Decaying pages with prev/recent clicks, absolute drop and drop percentage |
409 | No Google Search Console property connected |
curl -X GET https://app.seomatic.ai/api/v1/gsc/decaying-pages \ -H "Authorization: Bearer smk_live_..."
/gsc/page-queriesThe queries Search Console attributes to ONE page.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
url | query | string (uri) | yes | The page URL to inspect. Must be on the connected property. |
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 |
400 | Missing/invalid url, or url off-property |
409 | No Google Search Console property connected |
curl -X GET https://app.seomatic.ai/api/v1/gsc/page-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":[]}'/tools/find_cannibalizationreadDetect keyword cannibalization: queries where two or more of your pages compete for the same search, splitting clicks and destabilizing position. Returns the affected queries with each competing page…
| Name | Type | Required | Description |
|---|---|---|---|
days | number | no | |
minImpressions | number | no | Ignore queries below this impression volume |
| 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/find_cannibalization \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{"days":0,"minImpressions":0}'/tools/get_brand_splitreadSplit search performance into brand vs non-brand queries. Answers "is my SEO actually improving, or is growth just people searching my name?" Provide your brand terms; without them, the domain name i…
| Name | Type | Required | Description |
|---|---|---|---|
days | number | no | |
brandTerms | string[] | no | Brand words/variants, lowercase (e.g. ["seomatic"]). Defaults to the domain name. |
| 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_brand_split \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{"days":0,"brandTerms":[]}'/tools/find_ctr_outliersreadFind pages whose click-through rate is far below what their position should earn, using this site's own position-vs-CTR curve. These are title/meta rewrites with measurable upside: the ranking is alr…
| Name | Type | Required | Description |
|---|---|---|---|
days | number | no | |
minImpressions | number | no | Only judge pages with at least this many impressions |
| 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/find_ctr_outliers \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{"days":0,"minImpressions":0}'/tools/get_search_appearancereadBreak performance down by search appearance (rich results, FAQs, videos, product snippets...). Shows which enhanced results you already earn and how they convert vs plain listings - the case for addi…
| Name | Type | Required | Description |
|---|---|---|---|
days | number | no |
| 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_appearance \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{"days":0}'/tools/get_seasonality_baselinereadSixteen months of monthly performance with a year-over-year verdict: answers "is this drop a real loss or just my normal seasonal dip?" Use BEFORE alarming anyone about a traffic change.
| 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_seasonality_baseline \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{}'/tools/get_sitemaps_statusreadHealth of every sitemap submitted to Search Console: errors, warnings, pending processing, stale downloads, and submitted counts. First stop for "Google is not indexing my pages".
| 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_sitemaps_status \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{}'/tools/get_discover_news_performancereadPerformance in Google Discover, Google News, Image search, or Video search - surfaces GSC reports separately from web search. Zero rows means no presence on that surface (common, not an error).
| Name | Type | Required | Description |
|---|---|---|---|
surface | enum: discover | news | image | video | no | |
days | number | no |
| 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_discover_news_performance \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{"surface":"discover","days":0}'/tools/get_folder_performancereadRoll search performance up by URL folder (/blog/, /products/, /docs/...): clicks, impressions, page counts, and average position per site section. The agency-report view of where a site earns its tra…
| Name | Type | Required | Description |
|---|---|---|---|
days | number | no | |
depth | number | no | Path depth to group by (1 = /blog/, 2 = /blog/topic/) |
| 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_folder_performance \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{"days":0,"depth":0}'/tools/get_fresh_performancereadToday-and-yesterday search performance using GSC's fresh (provisional) data - hours old instead of the 2-3 day finalized lag. Numbers can still shift; use for "how is today going", never for reportin…
| 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_fresh_performance \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{}'Visibility, citations, and traffic inside AI answer engines: scans, tracked prompts, crawler activity, and first-party observed citations.
/pages/ai-activityPer-page AI engagement: answer-crawler fetches and AI-referred visits.
| 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 | Pages ranked by total AI engagement |
curl -X GET https://app.seomatic.ai/api/v1/pages/ai-activity \ -H "Authorization: Bearer smk_live_..."
/brand-factsStore the workspace's canonical business facts as AI ground truth.
| Name | Type | Required | Description |
|---|---|---|---|
site | string | no | Site URL the facts describe. |
facts | object | no | Allowlisted keys: name, legal_name, founded, founders, description, email, phone, address, sameas. |
| Status | Description |
|---|---|
200 | Stored |
400 | Invalid JSON body |
curl -X POST https://app.seomatic.ai/api/v1/brand-facts \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{"site":"…","facts":{}}'/tools/get_ai_visibilityreadRead the workspace's latest completed AI-search visibility scan: per-engine brand visibility (ChatGPT, Claude, Gemini, Perplexity, Grok, Google AI Overviews), the prompts where the brand was MISSED a…
| Name | Type | Required | Description |
|---|---|---|---|
scanId | string (uuid) | no | A specific scan to read (from recentScans). Omit for the latest completed scan. |
| 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_ai_visibility \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{"scanId":"00000000-0000-0000-0000-000000000000"}'/tools/run_ai_visibility_scanactsStart a FRESH AI-search visibility scan: queries the live AI engines (ChatGPT, Claude, Gemini, ...) with buyer-intent prompts and measures whether the brand appears. Scans YOUR OWN site by default; p…
| Name | Type | Required | Description |
|---|---|---|---|
domain | string | no | Competitor domain to scan instead of your own site, e.g. "competitor.com". Omit for your own site. |
| 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/run_ai_visibility_scan \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{"domain":"…"}'/tools/list_tracked_promptsactsThe AI-visibility monitor's tracked prompts (the questions scans ask every engine) with each prompt's id, active state and source, plus the plan's prompt allowance and current cadence. Cost: FREE - r…
| Name | Type | Required | Description |
|---|---|---|---|
locationCode | integer | no | Locale location code (default: the primary monitor locale) |
languageCode | string | no | Locale language code, e.g. "en" |
| 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_tracked_prompts \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{"locationCode":0,"languageCode":"…"}'/tools/add_tracked_promptactsAdd a tracked prompt to the AI-visibility monitor - a question future scans will ask every engine (e.g. 'best invoicing software for freelancers'). Plan-capped: a limit refusal returns the exact upgr…
| Name | Type | Required | Description |
|---|---|---|---|
prompt | string | yes | The buyer question to track, in the customer voice |
locationCode | integer | no | Locale location code (default: the primary monitor locale) |
languageCode | string | no | Locale language code, e.g. "en" |
| 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/add_tracked_prompt \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{"prompt":"…","locationCode":0,"languageCode":"…"}'/tools/update_tracked_promptactsEdit a tracked prompt: rename it, pin it, or activate/deactivate it (deactivated prompts keep history but stop being scanned; reactivation re-checks the plan cap). Get ids from list_tracked_prompts.…
| Name | Type | Required | Description |
|---|---|---|---|
promptId | string (uuid) | yes | From list_tracked_prompts |
text | string | no | |
pinned | boolean | no | |
active | boolean | 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/update_tracked_prompt \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{"promptId":"00000000-0000-0000-0000-000000000000","text":"…","pinned":true,"active":true}'/tools/remove_tracked_promptactsRemove a tracked prompt from the AI-visibility monitor permanently (prefer update_tracked_prompt active:false to pause without losing the row). Get ids from list_tracked_prompts. Confirm with the use…
| Name | Type | Required | Description |
|---|---|---|---|
promptId | string (uuid) | yes | From list_tracked_prompts |
| 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/remove_tracked_prompt \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{"promptId":"00000000-0000-0000-0000-000000000000"}'/tools/set_scan_cadenceactsChange how often AI-visibility scans run: 'weekly' (default), 'daily', or 'manual' (only when the user triggers one). SPEND LEVER: daily is ~7x the weekly scan cost and is plan-gated - set 'daily' ON…
| Name | Type | Required | Description |
|---|---|---|---|
cadence | enum: weekly | daily | manual | yes | |
locationCode | integer | no | Locale location code (default: the primary monitor locale) |
languageCode | string | no | Locale language code, e.g. "en" |
| 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/set_scan_cadence \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{"cadence":"weekly","locationCode":0,"languageCode":"…"}'/tools/get_ai_crawler_activityreadWhich AI bots (GPTBot, ChatGPT-User, PerplexityBot, ClaudeBot…) visited the user's site, classified by purpose (answer-time retrieval / AI-search indexing / model training), with per-bot trends, top…
| Name | Type | Required | Description |
|---|---|---|---|
windowDays | integer | no |
| 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_ai_crawler_activity \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{"windowDays":0}'/tools/get_trust_entitiesreadThe trust entities AI engines consult when answering questions about the user's market, mined from the ACTUAL fan-out queries our scans capture (site:-scoped searches + review platforms / analysts li…
| 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_trust_entities \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{}'/tools/get_ai_funnelreadThe full AI-search funnel per page of the user's site, joined across three measurements nobody else holds together: CITED (engines named the page as a source in tracked answers), CRAWLED (answer-time…
| 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_ai_funnel \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{}'/tools/get_observed_citationsreadRead citations of this site observed in REAL, logged-in AI answers (ChatGPT, Perplexity, Gemini, Copilot, Claude, Google AI Overviews), captured by the user's own browser extension. This is the one d…
| Name | Type | Required | Description |
|---|---|---|---|
days | integer | no | Look-back window in days (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_observed_citations \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{"days":0}'/tools/get_page_ai_activityreadRead which of this site's pages AI answer engines actually engage with: how many times AI answer crawlers FETCHED each page (the step that precedes a citation) and how many visits an AI assistant REF…
| Name | Type | Required | Description |
|---|---|---|---|
days | integer | no | Look-back window in days (1-90). Default 28. |
limit | integer | no | Max pages 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_page_ai_activity \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{"days":0,"limit":0}'/tools/get_brand_factsreadRead the canonical business facts this site publishes for AI answer engines (name, legal name, founding year, founders, description, contact, official profiles) plus its internal-link health reading.…
| 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_brand_facts \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{}'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_clustersreadThe 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) |
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}'/tools/find_link_prospectsreadFind LINK PROSPECTS: referring domains that link to the given competitors but NOT to this workspace's site (classic link intersect). A domain linking to several competitors is a pre-qualified, warm o…
| Name | Type | Required | Description |
|---|---|---|---|
competitors | string[] | yes | 1-3 competitor domains (e.g., ["competitor.com"]) |
limit | number | no | Max prospects to return (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/find_link_prospects \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{"competitors":[],"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 under…
| 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_snapshotreadCompact 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) |
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_strategyreadThe 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) |
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_signalreadRead 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. U…
| 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 | product_status | local_presence | local_visibility | citation_audit | link_equity | serp_snapshot | serp_displacements | rival_sitemaps | answer_shifts | 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) |
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_scoresreadAI-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) |
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 | completed | 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":"…"}'/tools/decide_seo_taskactsApprove or dismiss a STAGED task proposal. This is the human half of the approval loop (pairs with the task.awaiting_approval webhook event, so a decision can happen from Slack or any workflow instea…
| Name | Type | Required | Description |
|---|---|---|---|
taskId | string | yes | The task id (from list_seo_tasks or the task.awaiting_approval event) |
decision | enum: approve | dismiss | yes | |
confirmDestructive | boolean | no | Required true to APPROVE an indexation-destructive type (noindex, redirect). Attestation that a human explicitly confir… |
| 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/decide_seo_task \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{"taskId":"…","decision":"approve","confirmDestructive":true}'/tools/get_task_rollbackactsWhat the pipeline can RESTORE for an executed task: every live edit stores the page's full pre-edit state (rollback_data) before writing. Call this FIRST whenever the user reports an agent edit remov…
| Name | Type | Required | Description |
|---|---|---|---|
taskId | string (uuid) | yes | The executed 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_task_rollback \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{"taskId":"00000000-0000-0000-0000-000000000000"}'/tools/score_draftreadScore a DRAFT (or any pasted content) for AI-search answerability BEFORE publishing: the same deterministic AI Search Score signals the publish gate runs (answer-first structure, citations, freshness…
| Name | Type | Required | Description |
|---|---|---|---|
content | string | yes | The draft: HTML, or plain text/markdown (auto-wrapped) |
contentType | enum: guide | tutorial | listicle | review | roundup | comparison | case_study | research | opinion | no | The draft's shape; drives intent-aware signal weights (default guide) |
| 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/score_draft \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{"content":"…","contentType":"guide"}'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 br…
| 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_campaignactsApprove, pause, 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. approve: proposed → approved, releasing the…
| Name | Type | Required | Description |
|---|---|---|---|
campaignId | string (uuid) | yes | |
action | enum: approve | pause | resume | abandon | update_brief | yes | |
confirm | boolean | no | Required true for approve and abandon: attests the user explicitly asked for this (approve releases work + spend; aband… |
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":"approve","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 data…
| 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 pl… |
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 w… |
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,…
| 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 th… |
| 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 "w…
| 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/upload_csvreadStage CSV TEXT so it can be imported as a dataset. This exists for MCP Apps hosts: MCP has no file transport, so a widget reads the user's file in the browser and passes its text here, receiving the…
| Name | Type | Required | Description |
|---|---|---|---|
fileName | string | yes | The file's name, e.g. cities.csv |
csvContent | string | yes | The raw CSV text, header row first |
| 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/upload_csv \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{"fileName":"…","csvContent":"…"}'/tools/import_attachment_as_datasetreadPromote a spreadsheet the user uploaded IN THIS CONVERSATION (CSV/Excel - its preview carries an attachmentId) into a private dataset in their library. Call it when the user wants the file used as ca…
| Name | Type | Required | Description |
|---|---|---|---|
attachmentId | string (uuid) | yes | The attachmentId shown in the uploaded file preview |
name | string | no | Dataset name (defaults to the file name) |
| 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/import_attachment_as_dataset \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{"attachmentId":"00000000-0000-0000-0000-000000000000","name":"…"}'/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 {{…
| 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, audit, and inventory the site itself.
/page-auditScore one public page for AI/LLM answerability.
| Name | Type | Required | Description |
|---|---|---|---|
url | string (uri) | yes | |
client | string | no | Surface attribution, e.g. wp-ai-visibility. |
| Status | Description |
|---|---|
200 | Answerability scores and issues for the page |
400 | Invalid or non-public URL (SSRF-rejected) |
curl -X POST https://app.seomatic.ai/api/v1/page-audit \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{"url":"https://example.com/hook","client":"…"}'/link-densityStore the site's internal-linking health reading.
| Name | Type | Required | Description |
|---|---|---|---|
site | string | no | |
scanned | integer | no | Posts sampled (must be >= 1 to store). |
internal_links | integer | no | Internal links found across the sample. |
| Status | Description |
|---|---|
200 | Stored (or ignored when nothing was scanned) |
400 | Invalid JSON body |
curl -X POST https://app.seomatic.ai/api/v1/link-density \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{"site":"…","scanned":0,"internal_links":0}'/redirectsRedirect rules the agents approved for this workspace but could not apply. Only rules that survived every guard are returned.
| Status | Description |
|---|---|
200 | Applicable redirect rules for the workspace site |
401 | Missing or invalid API key |
403 | Key lacks the 'chat:ask' scope |
429 | Rate limited (per key). Retry-After header set. |
curl -X GET https://app.seomatic.ai/api/v1/redirects \ -H "Authorization: Bearer smk_live_..."
/redirects/{taskId}/ackRecord that a redirect rule is now live on the site. Starts the outcome-verification window. Repeating an ack is a no-op.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
taskId | path | string | yes |
| Status | Description |
|---|---|
200 | Recorded (or already recorded) |
401 | Missing or invalid API key |
404 | No such redirect rule in this workspace (REDIRECT_NOT_FOUND) |
429 | Rate limited (per key). Retry-After header set. |
curl -X POST https://app.seomatic.ai/api/v1/redirects/{taskId}/ack \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{}'/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_inventoryreadPages 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) |
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}'/tools/site_auditreadSite-WIDE technical SEO audit: crawls up to 30 of the workspace's pages (from the synced page inventory, or pass specific urls) and aggregates cross-page issues a single-page check cannot see - dupli…
| Name | Type | Required | Description |
|---|---|---|---|
urls | string[] | no | Specific pages to audit (max 30). Omit to audit the newest pages from the synced inventory. |
limit | integer | no | How many inventory pages to crawl when urls is omitted (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/site_audit \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{"urls":[],"limit":0}'Pay-as-you-go article generation, where the workspace AI credits went, and your referral link.
/articlesList purchased articles (bodies excluded) and the spendable prepaid balance.
| Status | Description |
|---|---|
200 | { balance, articles: [...] } |
401 | Missing or invalid API key |
429 | Rate limited (per key). Retry-After header set. |
curl -X GET https://app.seomatic.ai/api/v1/articles \ -H "Authorization: Bearer smk_live_..."
/articlesGenerate one SEO article from a topic (consumes 1 prepaid unit, $9 pay-as-you-go). Returns 202 + id; poll GET /articles/{id} until status=ready for markdown + html.
| Name | Type | Required | Description |
|---|---|---|---|
topic | string | yes | The keyword/topic to write about, e.g. "how to choose trail running shoes". |
| Status | Description |
|---|---|
202 | { id, status: "queued", poll } - generation runs async (typically a few minutes). |
400 | topic missing (INVALID_REQUEST) |
401 | Missing or invalid API key |
402 | No prepaid articles remaining (ARTICLE_BALANCE_EMPTY). Body carries buy_url; POST /articles/checkout returns a payment link. |
429 | Rate limited (per key). Retry-After header set. |
curl -X POST https://app.seomatic.ai/api/v1/articles \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{"topic":"…"}'/articles/{articleId}One article. When status=ready the body carries BOTH formats: markdown (source of truth) and html (rendered).
| Name | In | Type | Required | Description |
|---|---|---|---|---|
articleId | path | string (uuid) | yes |
| Status | Description |
|---|---|
200 | { article: { id, topic, status: queued|generating|ready|failed, title, markdown, html, wordCount, aiSearchScore, contentScore, featuredImageUrl } } |
401 | Missing or invalid API key |
404 | Article not found (NOT_FOUND) |
429 | Rate limited (per key). Retry-After header set. |
curl -X GET https://app.seomatic.ai/api/v1/articles/{articleId} \
-H "Authorization: Bearer smk_live_..."/articles/{articleId}Edit a delivered article: {title?, markdown?}. html is re-rendered server-side from markdown on every edit (never accepted from the caller). Free.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
articleId | path | string (uuid) | yes |
| Name | Type | Required | Description |
|---|---|---|---|
title | string | no | |
markdown | string | no | Full replacement markdown body. |
| Status | Description |
|---|---|
200 | { ok: true, id } |
400 | Neither title nor markdown provided |
401 | Missing or invalid API key |
404 | Not found, or article not ready yet (NOT_FOUND) |
429 | Rate limited (per key). Retry-After header set. |
curl -X PATCH https://app.seomatic.ai/api/v1/articles/{articleId} \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{"title":"…","markdown":"…"}'/articles/checkoutGet a Stripe payment link to top up the prepaid article balance ($9/article, quantity 1-52). Open the URL in a browser; the balance updates when Stripe confirms.
| Name | Type | Required | Description |
|---|---|---|---|
quantity | integer | no |
| Status | Description |
|---|---|
200 | { checkout_url } |
401 | Missing or invalid API key |
429 | Rate limited (per key). Retry-After header set. |
curl -X POST https://app.seomatic.ai/api/v1/articles/checkout \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{"quantity":0}'/articles/payPay for prepaid article units with a Stripe Shared Payment Token (agentic payments: Meta Muse, ChatGPT agentic checkout, link-cli). The user approves a bounded spend in their Link wallet; the agent passes the spt_ token here and the balance updates in the same response - no browser. Price is fixed server-side ($9/article); the token is single-use and amount-capped by Stripe.
| Name | Type | Required | Description |
|---|---|---|---|
spt_token | string | yes | A Stripe shared payment token (spt_...) granted by the buyer via their Link wallet. |
sku | enum: article | question_pack | visibility_scan | competitor_scan | no | What to buy: articles ($9 each), question packs ($5 for 50 assistant questions), AI-visibility scans of your site ($19), or competitor scans ($19). |
quantity | integer | no |
| Status | Description |
|---|---|
200 | { paid: true, quantity, amount_cents, currency, balance } |
400 | Missing or malformed spt_token |
401 | Missing or invalid API key |
402 | Payment failed - the token was already used, expired, or the amount exceeds what the user approved. The error message carries the exact reason to relay. |
429 | Rate limited (per key). Retry-After header set. |
curl -X POST https://app.seomatic.ai/api/v1/articles/pay \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{"spt_token":"…","sku":"article","quantity":0}'/articles/mppMachine Payments Protocol (MPP) payment link for article units. POST with no credential returns a 402 challenge that teaches any Link-wallet agent (link-cli) how to obtain a Shared Payment Token and retry; the same URL opened in a browser redirects to the human buy page. Links are minted by generate_article / POST /articles 402 payloads (mpp_payment_link) and are HMAC-signed - do not construct them by hand.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
t | query | string | no | Signed payment token from an mpp_payment_link (carries org and quantity). |
| Status | Description |
|---|---|
200 | { paid: true, quantity, amount_cents, currency, balance } plus an MPP receipt header |
400 | Missing, invalid, or expired payment link |
402 | MPP payment challenge (retry with an SPT credential) |
429 | Rate limited (per key). Retry-After header set. |
503 | Machine payments not enabled on this server yet |
curl -X POST https://app.seomatic.ai/api/v1/articles/mpp \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{}'/tools/generate_articlereadWrite one in-depth SEO article on a topic ($9, consumes 1 prepaid pay-as-you-go unit; no subscription required). Research-grounded against live rankings, quality-gated, delivered as markdown + HTML.…
| Name | Type | Required | Description |
|---|---|---|---|
topic | string | yes | The keyword/topic to write about, e.g. "how to choose trail running shoes". |
user_intent | string | no | One sentence on the user's goal for this article (optional). |
| 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/generate_article \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{"topic":"…","user_intent":"…"}'/tools/get_articlereadFetch a pay-as-you-go article by id (poll after generate_article), or omit article_id to list the most recent articles and the prepaid balance. A ready article carries BOTH formats: markdown (source…
| Name | Type | Required | Description |
|---|---|---|---|
article_id | string (uuid) | no | The id returned by generate_article. Omit to list. |
| 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_article \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{"article_id":"00000000-0000-0000-0000-000000000000"}'/tools/pay_for_articlesreadPay for prepaid units with a Stripe Shared Payment Token (spt_...) that YOUR PLATFORM minted after the user approved the spend in their Link wallet. Products: articles ($9 each, default), question_pa…
| Name | Type | Required | Description |
|---|---|---|---|
spt_token | string | yes | The Stripe shared payment token granted by the buyer via their Link wallet. |
sku | enum: article | question_pack | visibility_scan | competitor_scan | no | What to buy. Default: article. |
quantity | integer | no |
| 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/pay_for_articles \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{"spt_token":"…","sku":"article","quantity":0}'/tools/get_credit_usagereadWhere this workspace's AI credits went in the current billing period: customer-language groups (items) AND the raw per-feature ledger with event counts (features) - the per-agent/per-action granulari…
| 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_credit_usage \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{}'/tools/get_referral_linkreadThe user's personal SEOmatic referral link and reward status. Returns: shareUrl (their /?ref= link), their referral funnel counts (totalReferred, activated, converted), and rewards earned (questionsE…
| 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_referral_link \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{}'Ingest endpoints the SEOmatic WordPress plugin reports into.
/wp-eventReport a lifecycle moment a plugin detected on the site it runs on.
| Name | Type | Required | Description |
|---|---|---|---|
event | string | yes | The lifecycle event name (known set). |
agents | string[] | no | Blocked user-agents, where applicable. |
rule | string | no | The robots.txt rule line, where applicable. |
| Status | Description |
|---|---|
200 | Recorded |
400 | Unknown event or invalid payload |
curl -X POST https://app.seomatic.ai/api/v1/wp-event \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{"event":"…","agents":[],"rule":"…"}'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 '{}'The endpoints behind the Zapier integration (Infrastructure).
/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"}'