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 today, credited to your first payment.
Table of Contents
The SEOmatic SEO API gives your own code the same data and tools as SEOmatic's agents: Google Search Console performance, site audits, indexing checks, AI visibility, SEO tasks and articles. 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}.
A few curated endpoints cover the common reads, and the tool bridge runs every tool by name. The jobs people use it for most:
| Job | Call | What you get |
|---|---|---|
| Search Console data | GET /gsc/top-queries, GET /gsc/top-pages, GET /gsc/page-queries | Clicks, impressions, CTR and position from your own property, for reports and dashboards. |
| Traffic drops | GET /gsc/decaying-pages, POST /tools/compare_periods | The pages and queries that lost clicks against the previous period. |
| Site audits | POST /tools/site_audit | Crawls up to 30 pages for dead pages, broken internal links, duplicate titles, thin content, noindex, canonicals, redirects and slow pages. |
| Indexing checks | POST /tools/inspect_url_indexing | Whether Google has indexed a URL, and why not. |
| AI visibility | POST /tools/get_ai_visibility | Your latest scan: visibility per AI engine, the prompts where you were missed, and who was named instead. |
| SEO tasks | POST /tools/list_seo_tasks, POST /tools/decide_seo_task | Read the agent's proposed fixes and approve or dismiss them from your own tools. |
| Articles | POST /articles | A finished, quality-gated SEO article from a prepaid balance, in markdown and HTML. |
Prefer to let an AI assistant make the calls? The same tools are on the SEO MCP server for Claude, ChatGPT and Cursor, and in n8n, Zapier and Make.com workflows.
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_...POST /ask, POST /page-audit). Direct Search Console reads (GET /gsc/*) do not use it. Check what is left with GET /me: free_questions.remaining (null on a paid plan). When it runs out, tool calls return 402 FREE_QUOTA_EXCEEDED.smk_test_... keys authenticate and behave exactly like smk_live_... keys. Use them to keep CI or staging on a key you can rotate or revoke without touching production.401 INVALID_TOKEN; use a workspace API key here.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. A rate-limit 429 carries no code: its body gives retryAfter (seconds) and reset (when the window resets).
| Header | Meaning |
|---|---|
X-RateLimit-Limit | The ceiling for the window (500). |
X-RateLimit-Remaining | Requests left in the window. |
X-RateLimit-Reset | When the window resets, as an ISO 8601 timestamp. |
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": "Too many requests",
"message": "Rate limit exceeded. Please try again later.",
"retryAfter": 30,
"reset": "2026-09-24T10:01:00.000Z"
}Errors are JSON with a human error message and, on every error except the rate-limit 429 above, a stable code. Many add details, a reason, and an upgrade_url when a plan change fixes it. Branch on the code, not the message.
{
"error": "This API key does not have the 'agents:act' scope",
"code": "MISSING_SCOPE",
"reason": "plan_limit",
"details": { "required": "agents:act", "granted": ["read:gsc", "chat:ask"] },
"upgrade_url": "https://app.seomatic.ai/settings/billing?src=api"
}| 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. |
INVALID_TOKEN | 401 | A token issued to an MCP client (OAuth) was sent to the REST API. It only works on the MCP server. | Use a workspace API key (smk_live_...) for REST calls. |
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 trigger, search or connection test on a workspace with no paid plan or trial. | Zapier triggers and searches work on any paid plan or trial. The body's `upgrade_url` links to the entry paid plan. Zapier actions also need Infrastructure (REST_ACT_REQUIRES_INFRA). |
AUTOMATION_NOT_ENTITLED | 402 | A call from the n8n node or the Make app (X-Seomatic-Client: n8n or make) on a workspace with no paid plan or trial. | The n8n and Make integrations work on any paid plan or trial. The body's `upgrade_url` links to billing. Acting tools also need Infrastructure (REST_ACT_REQUIRES_INFRA). |
FREE_QUOTA_EXCEEDED | 402 | A free workspace used its 5 questions this month (shared across the app, MCP and REST). | Upgrade from `upgrade_url`, or buy a question pack. GET /v1/me shows `free_questions.remaining`. |
BILLING_INACTIVE | 402 | The subscription is paused or its card was declined. | Follow the link in the body to resume or update the card. Upgrading does not fix it. |
SCOPE_REVOKED_BY_PLAN | 402 | The key has an acting scope, but the plan no longer includes acting through the API. | Upgrade from `upgrade_url`, or use a read-only key. |
INSUFFICIENT_CREDITS | 402 | A tool needs more AI credits than the workspace has left this period. | Credits renew each billing period. `upgrade_url` opens the credit packs to add more now. `result` holds the tool's message. |
PAYMENT_REQUIRED | 402 | A tool needs a one-time payment before it runs (for example an article). | Pay from the link in `result`, then call again. |
PROMPT_LIMIT, WORKSPACE_LIMIT_EXCEEDED, … | 402 | A tool hit a plan limit (tracked prompts, monitors, pages, seats, workspaces) or a feature the plan does not include (codes ending in _NOT_ENTITLED, PLANNER_DISABLED, AUTO_EXECUTE_DISABLED). The full list is in the OpenAPI spec. | Upgrade from `upgrade_url` (with `reason` saying which limit). `result` holds the tool's message. |
NEEDS_CONFIRMATION | 422 | The tool needs a confirmation step before it acts. | Read `result`, then call again with the confirmation it asks for. |
TOOL_REFUSED | 422 | The tool declined for a reason it states. | Read the explanation in `result` and fix what it names. |
INVALID_ARGUMENTS | 400 | The request body failed the tool's schema. | `details` is a string naming the failing fields. Check them against the parameter table. |
INVALID_REQUEST | 400 | An endpoint's body is missing a required field or has a bad value (for example POST /v1/articles without `topic`). | Read `error` and `details.hint`, fix the body, and retry. |
BAD_URL | 400 | GET /v1/gsc/page-queries without a valid page `url`. | Pass an absolute page URL. |
OFF_PROPERTY | 400 | The page `url` is not on the connected Search Console property. | Use a URL on the property the workspace has connected. |
BODY_TOO_LARGE | 413 | A POST /v1/tools/{name} body over 256 KB. | Send smaller arguments. Tool arguments are small JSON objects. |
NOT_FOUND | 404 | No such article in this key's organization, or it is not ready yet (PATCH). | Check the id. Poll GET /v1/articles/{id} until `status` is `ready` before editing. |
ARTICLE_BALANCE_EMPTY | 402 | POST /v1/articles with no prepaid articles left. | Buy more from `buy_url`, POST /v1/articles/checkout for a payment link, or pay `mpp_payment_link`. |
ARTICLE_FAILURE_CAP | 429 | Too many API articles failed in the last 24 hours. `scope` is `caller` (this caller_ref) or `org` (the whole organization). | Retry after `Retry-After` (3600 seconds). Nothing was charged. |
ARTICLE_CANCEL_LIMIT | 429 | Too many canceled articles in the last 24 hours. | The article keeps generating and is delivered as usual. Retry-After is 3600 seconds. |
ARTICLE_ALREADY_READY | 409 | Cancel on an article that already finished. | Nothing to cancel. Fetch it with GET /v1/articles/{id}. |
ARTICLE_ALREADY_FAILED | 409 | Cancel on an article that already failed. | Its unit was already returned. Nothing to do. |
LIMIT_REACHED | 409 | POST /v1/webhooks on a workspace that already has 25 endpoints. | Delete an endpoint you no longer use, then register the new one. |
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. |
TOOL_TIMEOUT | 504 | A tool is still running after the 60s response ceiling. It was not stopped. | With an Idempotency-Key, repeat the same request to collect the answer. Without one, check the result before calling an acting tool again. |
INVALID_IDEMPOTENCY_KEY | 400 | The Idempotency-Key header is not 1-255 printable ASCII characters. | Send a UUID per logical call. |
IDEMPOTENCY_IN_PROGRESS | 409 | A request with this Idempotency-Key is still running. | Repeat the same request after Retry-After to collect the result. |
IDEMPOTENCY_RESULT_NOT_KEPT | 409 | The call with this Idempotency-Key ran, but its answer was over 64 KB, so it was returned once and not stored. | The tool is not run again. Read the outcome with a read tool, or use a new key for a new call. |
IDEMPOTENCY_KEY_REUSED | 422 | The Idempotency-Key was already used for a different tool or arguments. | Use a new key for a new call. |
PROVIDER_UNAVAILABLE | 503 | The SEO data provider or the credit check is down on our side. Not a limit. | Retry shortly. Nothing was charged. |
IDEMPOTENCY_UNAVAILABLE | 503 | Idempotency is temporarily unavailable, so the tool was not run. | Retry after Retry-After. Nothing ran, so the retry is safe. |
A successful POST /tools/{name} answers 200 with { tool, result }. resultis the tool's output as a JSON string, so parse it before reading fields. A tool that refuses answers a real HTTP error instead: 402 for credits, a payment or a plan limit, 422 when it needs a confirmation or declines, 429 when throttled and 503 when a data provider is down on our side. The body names the code, carries upgrade_urlwhen an upgrade is the fix, and keeps the tool's own message in result.
const res = await fetch(
"https://app.seomatic.ai/api/v1/tools/get_search_queries",
{
method: "POST",
headers: {
Authorization: `Bearer ${process.env.SEOMATIC_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({ days: 28 }),
},
);
const body = await res.json();
if (!res.ok) {
// refused: body.code says why, body.upgrade_url is the fix when there is one
throw new Error(`${body.code}: ${body.error}`);
}
const data =
typeof body.result === "string" ? JSON.parse(body.result) : body.result;Send an Idempotency-Key header (a UUID per logical call) on POST /tools/{name} to make the call safe to repeat. The first request runs the tool. A repeat with the same key and the same arguments returns that run's response with Idempotent-Replayed: true, or 409 while it still runs. An acting tool never runs twice.
409 IDEMPOTENCY_RESULT_NOT_KEPT and the tool is not run again.curl -X POST "https://app.seomatic.ai/api/v1/tools/decide_seo_task" \
-H "Authorization: Bearer $SEOMATIC_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"taskId": "<task id>", "decision": "approve"}'To repeat a call safely, reuse the same key: generate it once, store it with the job, and send that value on every retry.
A tool answers within 60 seconds. A slower one returns 504 TOOL_TIMEOUT and keeps running; it is not stopped. With an Idempotency-Key, repeat the request to collect its answer. Without one, check the outcome before calling an acting tool again.
Order a finished, quality-gated SEO article from a prepaid balance, with no subscription. The key needs the chat:ask scope and the organization needs prepaid articles; with none left, the call returns 402 ARTICLE_BALANCE_EMPTY with a buy_url.
POST /articles with {"topic": "..."} spends one unit and answers 202 with the article id.GET /articles/{id} until status is ready (it moves through queued and generating; it can also end failed, which returns the unit, or canceled). A ready article carries both markdown and html.POST /articles/{id}/cancel on a queued or generating article returns {"status": "canceled", "refunded": true} and gives the unit back. Repeating the cancel is safe: it answers the same status with refunded: false and already_canceled.If you resell articles to your own customers through one SEOmatic organization, send an optional caller_ref (1 to 128 characters of letters, digits and . _ : @ -) per end customer. The daily caps on failed and canceled articles then apply to each caller_ref separately, so one customer's failures never block the others.
curl -X POST "https://app.seomatic.ai/api/v1/articles" \
-H "Authorization: Bearer $SEOMATIC_API_KEY" \
-H "Content-Type: application/json" \
-d '{"topic": "how to choose running shoes", "caller_ref": "customer-42"}'
# 202 {"id": "<article id>", "status": "queued", "poll": "/api/v1/articles/<article id>"}
curl "https://app.seomatic.ai/api/v1/articles/$ARTICLE_ID" \
-H "Authorization: Bearer $SEOMATIC_API_KEY"The n8n node and the Make app call this API with your key and identify themselves with an X-Seomatic-Client header. SEOmatic uses it to apply the integration's plan rule: like Zapier, n8n and Make work on any paid plan or trial, checked on every call, including the connection test. A workspace with neither gets 402 AUTOMATION_NOT_ENTITLED. Acting tools still need the Infrastructure plan (402 REST_ACT_REQUIRES_INFRA). Calls without the header follow the plain REST rules.
Authorization: Bearer smk_live_...
X-Seomatic-Client: n8n{
"error": "The n8n integration works on any paid plan or trial. This workspace has neither right now.",
"code": "AUTOMATION_NOT_ENTITLED",
"reason": "features",
"upgrade_url": "https://app.seomatic.ai/settings/billing?src=api"
}Automations never spend prepaid scans. Over this API (Zapier, n8n, Make and your own scripts), run_ai_visibility_scan runs on the workspace's AI credits. When they cannot cover the scan, the call answers 402 INSUFFICIENT_CREDITS instead of using a prepaid scan. Prepaid scans are only spent from the SEOmatic app or an MCP agent. The last stored scan stays readable for free with get_ai_visibility.
{
"tool": "run_ai_visibility_scan",
"error": "Tool 'run_ai_visibility_scan' did not complete: INSUFFICIENT_CREDITS",
"code": "INSUFFICIENT_CREDITS",
"upgrade_url": "https://app.seomatic.ai/dashboard/settings?tab=billing",
"result": "{\"status\":\"insufficient_credits\",\"scan_target\":\"own site\",\"message\":\"Not enough AI credits for a fresh scan (needs ~<n> credits). Automations never spend prepaid scans; run this scan from the SEOmatic app, or add credits. The last stored scan is still readable free via get_ai_visibility.\"}"
}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).
| Name | In | Type | Required | Description |
|---|---|---|---|---|
X-Seomatic-Client | header | enum: n8n | make | no | Identifies an automation-platform integration (the official n8n node sends `n8n`, the Make app sends `make`). When set, every call, including a connection test against /me, requires a paid plan or a trial (reads work on any of them; acting tools still need Infrastructure), else 402 AUTOMATION_NOT_ENTITLED. Omit it for plain REST usage. |
| Status | Description |
|---|---|
200 | Key and workspace details |
401 | Missing or invalid API key |
402 | X-Seomatic-Client is n8n or make and the workspace has no paid plan or trial (AUTOMATION_NOT_ENTITLED). Body carries upgrade_url. |
429 | Rate limited (per key). Retry-After header set. |
curl -X GET "https://app.seomatic.ai/api/v1/me" \
-H "Authorization: Bearer $SEOMATIC_API_KEY"/toolsList every tool this key can call (name, description, input JSON Schema, acts flag): the full REST capability surface, identical to MCP.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
X-Seomatic-Client | header | enum: n8n | make | no | Identifies an automation-platform integration (the official n8n node sends `n8n`, the Make app sends `make`). When set, every call, including a connection test against /me, requires a paid plan or a trial (reads work on any of them; acting tools still need Infrastructure), else 402 AUTOMATION_NOT_ENTITLED. Omit it for plain REST usage. |
| Status | Description |
|---|---|
200 | Scope-filtered tool roster. Each: {name, description, input_schema, acts}. |
401 | Missing or invalid API key |
402 | X-Seomatic-Client is n8n or make and the workspace has no paid plan or trial (AUTOMATION_NOT_ENTITLED). Body carries upgrade_url. |
429 | Rate limited (per key). Retry-After header set. |
curl -X GET "https://app.seomatic.ai/api/v1/tools" \
-H "Authorization: Bearer $SEOMATIC_API_KEY"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.
The non-streaming sibling of dashboard chat, for surfaces that cannot hold an sse stream open (WordPress plugins, n8n, curl). The roster is the same scope-filtered set MCP and /tools serve, so a free key can read and ask but never act. Metered against the workspace's monthly question pool (shared with chat and MCP); a model failure does not consume a question.
| 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; free workspaces also get remaining_questions in the body. |
400 | Missing or invalid question |
402 | Monthly question limit reached (FREE_QUOTA_EXCEEDED; body carries keep_going_url, the page with every way to continue), or the subscription is paused or its card was declined (BILLING_INACTIVE; body links the one step that restores it). |
curl -X POST "https://app.seomatic.ai/api/v1/ask" \
-H "Authorization: Bearer $SEOMATIC_API_KEY" \
-H "Content-Type: application/json" \
-d '{"question":"…"}'The first answer about your own site: can Google index it, what the numbers say, and the top 3 fixes ranked by impact.
/tools/get_startedreadStart here for any first question about the user's own site ("how is my site doing", "what should I fix", "where do I start"). One answer: whether Google can index the site (status, redirects, noinde…
| Name | Type | Required | Description |
|---|---|---|---|
site | string | no | The user's OWN website, only if the workspace has none on record yet (the answer says so). Never a competitor. |
confirmed_own | boolean | no | Set true only after the user confirmed that `site` is their own website; the workspace then remembers it. |
topic | string | no | What the business sells or does, in the words a customer would search (e.g. "wedding photographer lyon"). Use when no s… |
| Status | Description |
|---|---|
200 | { tool, result }: the tool answered. result is its output, usually a JSON string (parse it). A tool that refuses does NOT answer 200: it gets the matching 402/422/429/503 below, with its own output in result. |
400 | Invalid arguments (INVALID_ARGUMENTS; details says what) or a malformed Idempotency-Key (INVALID_IDEMPOTENCY_KEY). |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA); the plan does not include acting through the API (SCOPE_REVOKED_BY_PLAN); X-Seomatic-Client is n8n or make and the workspace has no paid plan or trial (AUTOMATION_NOT_ENTITLED); the free monthly question limit is reached (FREE_QUOTA_EXCEEDED; body carries keep_going_url and a question_pack payment link); the subscription is paused or its card was declined (BILLING_INACTIVE; body links the one step that restores it, never an upgrade); or the tool refused for credits (INSUFFICIENT_CREDITS, PAYMENT_REQUIRED; body carries the tool result); or the tool hit a plan limit (the code is the refusal code itself: PROMPT_LIMIT, CADENCE_LIMIT, MONITOR_LIMIT, PAGE_LIMIT_EXCEEDED, SEAT_LIMIT_EXCEEDED, WORKSPACE_LIMIT_EXCEEDED, PLANNER_DISABLED, AUTO_EXECUTE_DISABLED, AGENT_SKILLS_NOT_ENTITLED, PAGE_TEMPLATES_NOT_ENTITLED, HOSTED_PAGES_NOT_ENTITLED, AI_ATTRIBUTION_NOT_ENTITLED, ZAPIER_NOT_ENTITLED, BYO_KEYS_NOT_ENTITLED, INCREMENTALITY_NOT_ENTITLED, WEBHOOKS_NOT_ENTITLED; `result` holds the tool refusal). Body carries upgrade_url (and reason, for tool refusals) where an upgrade is the fix. |
403 | The plan allows it but the key creator's role in the workspace does not (FORBIDDEN_ROLE; e.g. a creator now a viewer calling an acting tool). No upgrade fixes it: an admin changes the role. |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
409 | A request with this Idempotency-Key is still running (IDEMPOTENCY_IN_PROGRESS; repeat after Retry-After to collect the result), or it ran and its answer was too large to keep (IDEMPOTENCY_RESULT_NOT_KEPT; it is not run again). |
413 | Request body over 256 KB (BODY_TOO_LARGE). Tool arguments are small JSON objects. |
422 | The tool refused: it needs a confirmation step first (NEEDS_CONFIRMATION), or it declined for another reason it states (TOOL_REFUSED); result holds its explanation. Or this Idempotency-Key was used for a different tool or arguments (IDEMPOTENCY_KEY_REUSED). |
429 | Rate limited: the per-key tool-call limit (Retry-After header set), or the tool refused for a rate cap (e.g. ARTICLE_FAILURE_CAP; body carries the tool result). |
502 | Tool execution failed (TOOL_FAILED) |
503 | Temporarily unavailable, on our side, not a limit: the upstream data provider or the credit check is down (PROVIDER_UNAVAILABLE; nothing was charged), or idempotency is unavailable and the tool was NOT run (IDEMPOTENCY_UNAVAILABLE). Retry shortly. |
504 | The tool is still running past the 60s response ceiling and was not stopped (TOOL_TIMEOUT). With an Idempotency-Key, repeat the request to collect its answer. |
curl -X POST "https://app.seomatic.ai/api/v1/tools/get_started" \
-H "Authorization: Bearer $SEOMATIC_API_KEY"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 $SEOMATIC_API_KEY"/gsc/decaying-pagesPages that LOST clicks: the recent window vs the adjacent window before it.
Content decay from the workspace's own Search Console property. A page must have had real prior traffic (minimum prior clicks) to count as decayed, so a page that never ranked is not reported as declining. Sorted by biggest click drop.
| 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 $SEOMATIC_API_KEY"/gsc/page-queriesThe queries Search Console attributes to ONE page.
Page-filtered query performance. The url must belong to the connected property (apex or subdomain); anything else is rejected.
| 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?url=https%3A%2F%2Fexample.com%2Fpage" \
-H "Authorization: Bearer $SEOMATIC_API_KEY"/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 $SEOMATIC_API_KEY"/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 answered. result is its output, usually a JSON string (parse it). A tool that refuses does NOT answer 200: it gets the matching 402/422/429/503 below, with its own output in result. |
400 | Invalid arguments (INVALID_ARGUMENTS; details says what) or a malformed Idempotency-Key (INVALID_IDEMPOTENCY_KEY). |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA); the plan does not include acting through the API (SCOPE_REVOKED_BY_PLAN); X-Seomatic-Client is n8n or make and the workspace has no paid plan or trial (AUTOMATION_NOT_ENTITLED); the free monthly question limit is reached (FREE_QUOTA_EXCEEDED; body carries keep_going_url and a question_pack payment link); the subscription is paused or its card was declined (BILLING_INACTIVE; body links the one step that restores it, never an upgrade); or the tool refused for credits (INSUFFICIENT_CREDITS, PAYMENT_REQUIRED; body carries the tool result); or the tool hit a plan limit (the code is the refusal code itself: PROMPT_LIMIT, CADENCE_LIMIT, MONITOR_LIMIT, PAGE_LIMIT_EXCEEDED, SEAT_LIMIT_EXCEEDED, WORKSPACE_LIMIT_EXCEEDED, PLANNER_DISABLED, AUTO_EXECUTE_DISABLED, AGENT_SKILLS_NOT_ENTITLED, PAGE_TEMPLATES_NOT_ENTITLED, HOSTED_PAGES_NOT_ENTITLED, AI_ATTRIBUTION_NOT_ENTITLED, ZAPIER_NOT_ENTITLED, BYO_KEYS_NOT_ENTITLED, INCREMENTALITY_NOT_ENTITLED, WEBHOOKS_NOT_ENTITLED; `result` holds the tool refusal). Body carries upgrade_url (and reason, for tool refusals) where an upgrade is the fix. |
403 | The plan allows it but the key creator's role in the workspace does not (FORBIDDEN_ROLE; e.g. a creator now a viewer calling an acting tool). No upgrade fixes it: an admin changes the role. |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
409 | A request with this Idempotency-Key is still running (IDEMPOTENCY_IN_PROGRESS; repeat after Retry-After to collect the result), or it ran and its answer was too large to keep (IDEMPOTENCY_RESULT_NOT_KEPT; it is not run again). |
413 | Request body over 256 KB (BODY_TOO_LARGE). Tool arguments are small JSON objects. |
422 | The tool refused: it needs a confirmation step first (NEEDS_CONFIRMATION), or it declined for another reason it states (TOOL_REFUSED); result holds its explanation. Or this Idempotency-Key was used for a different tool or arguments (IDEMPOTENCY_KEY_REUSED). |
429 | Rate limited: the per-key tool-call limit (Retry-After header set), or the tool refused for a rate cap (e.g. ARTICLE_FAILURE_CAP; body carries the tool result). |
502 | Tool execution failed (TOOL_FAILED) |
503 | Temporarily unavailable, on our side, not a limit: the upstream data provider or the credit check is down (PROVIDER_UNAVAILABLE; nothing was charged), or idempotency is unavailable and the tool was NOT run (IDEMPOTENCY_UNAVAILABLE). Retry shortly. |
504 | The tool is still running past the 60s response ceiling and was not stopped (TOOL_TIMEOUT). With an Idempotency-Key, repeat the request to collect its answer. |
curl -X POST "https://app.seomatic.ai/api/v1/tools/get_search_queries" \
-H "Authorization: Bearer $SEOMATIC_API_KEY"/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 answered. result is its output, usually a JSON string (parse it). A tool that refuses does NOT answer 200: it gets the matching 402/422/429/503 below, with its own output in result. |
400 | Invalid arguments (INVALID_ARGUMENTS; details says what) or a malformed Idempotency-Key (INVALID_IDEMPOTENCY_KEY). |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA); the plan does not include acting through the API (SCOPE_REVOKED_BY_PLAN); X-Seomatic-Client is n8n or make and the workspace has no paid plan or trial (AUTOMATION_NOT_ENTITLED); the free monthly question limit is reached (FREE_QUOTA_EXCEEDED; body carries keep_going_url and a question_pack payment link); the subscription is paused or its card was declined (BILLING_INACTIVE; body links the one step that restores it, never an upgrade); or the tool refused for credits (INSUFFICIENT_CREDITS, PAYMENT_REQUIRED; body carries the tool result); or the tool hit a plan limit (the code is the refusal code itself: PROMPT_LIMIT, CADENCE_LIMIT, MONITOR_LIMIT, PAGE_LIMIT_EXCEEDED, SEAT_LIMIT_EXCEEDED, WORKSPACE_LIMIT_EXCEEDED, PLANNER_DISABLED, AUTO_EXECUTE_DISABLED, AGENT_SKILLS_NOT_ENTITLED, PAGE_TEMPLATES_NOT_ENTITLED, HOSTED_PAGES_NOT_ENTITLED, AI_ATTRIBUTION_NOT_ENTITLED, ZAPIER_NOT_ENTITLED, BYO_KEYS_NOT_ENTITLED, INCREMENTALITY_NOT_ENTITLED, WEBHOOKS_NOT_ENTITLED; `result` holds the tool refusal). Body carries upgrade_url (and reason, for tool refusals) where an upgrade is the fix. |
403 | The plan allows it but the key creator's role in the workspace does not (FORBIDDEN_ROLE; e.g. a creator now a viewer calling an acting tool). No upgrade fixes it: an admin changes the role. |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
409 | A request with this Idempotency-Key is still running (IDEMPOTENCY_IN_PROGRESS; repeat after Retry-After to collect the result), or it ran and its answer was too large to keep (IDEMPOTENCY_RESULT_NOT_KEPT; it is not run again). |
413 | Request body over 256 KB (BODY_TOO_LARGE). Tool arguments are small JSON objects. |
422 | The tool refused: it needs a confirmation step first (NEEDS_CONFIRMATION), or it declined for another reason it states (TOOL_REFUSED); result holds its explanation. Or this Idempotency-Key was used for a different tool or arguments (IDEMPOTENCY_KEY_REUSED). |
429 | Rate limited: the per-key tool-call limit (Retry-After header set), or the tool refused for a rate cap (e.g. ARTICLE_FAILURE_CAP; body carries the tool result). |
502 | Tool execution failed (TOOL_FAILED) |
503 | Temporarily unavailable, on our side, not a limit: the upstream data provider or the credit check is down (PROVIDER_UNAVAILABLE; nothing was charged), or idempotency is unavailable and the tool was NOT run (IDEMPOTENCY_UNAVAILABLE). Retry shortly. |
504 | The tool is still running past the 60s response ceiling and was not stopped (TOOL_TIMEOUT). With an Idempotency-Key, repeat the request to collect its answer. |
curl -X POST "https://app.seomatic.ai/api/v1/tools/get_top_pages" \
-H "Authorization: Bearer $SEOMATIC_API_KEY"/tools/get_dimension_breakdownreadBreak down Google Search Console performance by device (desktop/mobile/tablet), country, date, query or page, optionally filtered to one exact query or one exact page. dimension=query with filterPage…
| Name | Type | Required | Description |
|---|---|---|---|
dimension | enum: device | country | date | query | page | yes | What to break performance down by: device, country, date, query (pair with filterPage for one page's queries) or page (… |
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 answered. result is its output, usually a JSON string (parse it). A tool that refuses does NOT answer 200: it gets the matching 402/422/429/503 below, with its own output in result. |
400 | Invalid arguments (INVALID_ARGUMENTS; details says what) or a malformed Idempotency-Key (INVALID_IDEMPOTENCY_KEY). |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA); the plan does not include acting through the API (SCOPE_REVOKED_BY_PLAN); X-Seomatic-Client is n8n or make and the workspace has no paid plan or trial (AUTOMATION_NOT_ENTITLED); the free monthly question limit is reached (FREE_QUOTA_EXCEEDED; body carries keep_going_url and a question_pack payment link); the subscription is paused or its card was declined (BILLING_INACTIVE; body links the one step that restores it, never an upgrade); or the tool refused for credits (INSUFFICIENT_CREDITS, PAYMENT_REQUIRED; body carries the tool result); or the tool hit a plan limit (the code is the refusal code itself: PROMPT_LIMIT, CADENCE_LIMIT, MONITOR_LIMIT, PAGE_LIMIT_EXCEEDED, SEAT_LIMIT_EXCEEDED, WORKSPACE_LIMIT_EXCEEDED, PLANNER_DISABLED, AUTO_EXECUTE_DISABLED, AGENT_SKILLS_NOT_ENTITLED, PAGE_TEMPLATES_NOT_ENTITLED, HOSTED_PAGES_NOT_ENTITLED, AI_ATTRIBUTION_NOT_ENTITLED, ZAPIER_NOT_ENTITLED, BYO_KEYS_NOT_ENTITLED, INCREMENTALITY_NOT_ENTITLED, WEBHOOKS_NOT_ENTITLED; `result` holds the tool refusal). Body carries upgrade_url (and reason, for tool refusals) where an upgrade is the fix. |
403 | The plan allows it but the key creator's role in the workspace does not (FORBIDDEN_ROLE; e.g. a creator now a viewer calling an acting tool). No upgrade fixes it: an admin changes the role. |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
409 | A request with this Idempotency-Key is still running (IDEMPOTENCY_IN_PROGRESS; repeat after Retry-After to collect the result), or it ran and its answer was too large to keep (IDEMPOTENCY_RESULT_NOT_KEPT; it is not run again). |
413 | Request body over 256 KB (BODY_TOO_LARGE). Tool arguments are small JSON objects. |
422 | The tool refused: it needs a confirmation step first (NEEDS_CONFIRMATION), or it declined for another reason it states (TOOL_REFUSED); result holds its explanation. Or this Idempotency-Key was used for a different tool or arguments (IDEMPOTENCY_KEY_REUSED). |
429 | Rate limited: the per-key tool-call limit (Retry-After header set), or the tool refused for a rate cap (e.g. ARTICLE_FAILURE_CAP; body carries the tool result). |
502 | Tool execution failed (TOOL_FAILED) |
503 | Temporarily unavailable, on our side, not a limit: the upstream data provider or the credit check is down (PROVIDER_UNAVAILABLE; nothing was charged), or idempotency is unavailable and the tool was NOT run (IDEMPOTENCY_UNAVAILABLE). Retry shortly. |
504 | The tool is still running past the 60s response ceiling and was not stopped (TOOL_TIMEOUT). With an Idempotency-Key, repeat the request to collect its answer. |
curl -X POST "https://app.seomatic.ai/api/v1/tools/get_dimension_breakdown" \
-H "Authorization: Bearer $SEOMATIC_API_KEY" \
-H "Content-Type: application/json" \
-d '{"dimension":"device"}'/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 answered. result is its output, usually a JSON string (parse it). A tool that refuses does NOT answer 200: it gets the matching 402/422/429/503 below, with its own output in result. |
400 | Invalid arguments (INVALID_ARGUMENTS; details says what) or a malformed Idempotency-Key (INVALID_IDEMPOTENCY_KEY). |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA); the plan does not include acting through the API (SCOPE_REVOKED_BY_PLAN); X-Seomatic-Client is n8n or make and the workspace has no paid plan or trial (AUTOMATION_NOT_ENTITLED); the free monthly question limit is reached (FREE_QUOTA_EXCEEDED; body carries keep_going_url and a question_pack payment link); the subscription is paused or its card was declined (BILLING_INACTIVE; body links the one step that restores it, never an upgrade); or the tool refused for credits (INSUFFICIENT_CREDITS, PAYMENT_REQUIRED; body carries the tool result); or the tool hit a plan limit (the code is the refusal code itself: PROMPT_LIMIT, CADENCE_LIMIT, MONITOR_LIMIT, PAGE_LIMIT_EXCEEDED, SEAT_LIMIT_EXCEEDED, WORKSPACE_LIMIT_EXCEEDED, PLANNER_DISABLED, AUTO_EXECUTE_DISABLED, AGENT_SKILLS_NOT_ENTITLED, PAGE_TEMPLATES_NOT_ENTITLED, HOSTED_PAGES_NOT_ENTITLED, AI_ATTRIBUTION_NOT_ENTITLED, ZAPIER_NOT_ENTITLED, BYO_KEYS_NOT_ENTITLED, INCREMENTALITY_NOT_ENTITLED, WEBHOOKS_NOT_ENTITLED; `result` holds the tool refusal). Body carries upgrade_url (and reason, for tool refusals) where an upgrade is the fix. |
403 | The plan allows it but the key creator's role in the workspace does not (FORBIDDEN_ROLE; e.g. a creator now a viewer calling an acting tool). No upgrade fixes it: an admin changes the role. |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
409 | A request with this Idempotency-Key is still running (IDEMPOTENCY_IN_PROGRESS; repeat after Retry-After to collect the result), or it ran and its answer was too large to keep (IDEMPOTENCY_RESULT_NOT_KEPT; it is not run again). |
413 | Request body over 256 KB (BODY_TOO_LARGE). Tool arguments are small JSON objects. |
422 | The tool refused: it needs a confirmation step first (NEEDS_CONFIRMATION), or it declined for another reason it states (TOOL_REFUSED); result holds its explanation. Or this Idempotency-Key was used for a different tool or arguments (IDEMPOTENCY_KEY_REUSED). |
429 | Rate limited: the per-key tool-call limit (Retry-After header set), or the tool refused for a rate cap (e.g. ARTICLE_FAILURE_CAP; body carries the tool result). |
502 | Tool execution failed (TOOL_FAILED) |
503 | Temporarily unavailable, on our side, not a limit: the upstream data provider or the credit check is down (PROVIDER_UNAVAILABLE; nothing was charged), or idempotency is unavailable and the tool was NOT run (IDEMPOTENCY_UNAVAILABLE). Retry shortly. |
504 | The tool is still running past the 60s response ceiling and was not stopped (TOOL_TIMEOUT). With an Idempotency-Key, repeat the request to collect its answer. |
curl -X POST "https://app.seomatic.ai/api/v1/tools/get_query_page_matrix" \
-H "Authorization: Bearer $SEOMATIC_API_KEY"/tools/get_query_pagesreadWhich pages rank for specific search queries, with page-level clicks, impressions, CTR and average position for each (query, page) pair, best page first - plus the query's site-wide total, labelled s…
| Name | Type | Required | Description |
|---|---|---|---|
queries | string[] | yes | Exact search queries (1-5), as they appear in GSC |
page | string | no | Optional full page URL to check against each query (returns its own row or null) |
days | number | no | Look-back window in finalized days (1-90, default 28) |
| Status | Description |
|---|---|
200 | { tool, result }: the tool answered. result is its output, usually a JSON string (parse it). A tool that refuses does NOT answer 200: it gets the matching 402/422/429/503 below, with its own output in result. |
400 | Invalid arguments (INVALID_ARGUMENTS; details says what) or a malformed Idempotency-Key (INVALID_IDEMPOTENCY_KEY). |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA); the plan does not include acting through the API (SCOPE_REVOKED_BY_PLAN); X-Seomatic-Client is n8n or make and the workspace has no paid plan or trial (AUTOMATION_NOT_ENTITLED); the free monthly question limit is reached (FREE_QUOTA_EXCEEDED; body carries keep_going_url and a question_pack payment link); the subscription is paused or its card was declined (BILLING_INACTIVE; body links the one step that restores it, never an upgrade); or the tool refused for credits (INSUFFICIENT_CREDITS, PAYMENT_REQUIRED; body carries the tool result); or the tool hit a plan limit (the code is the refusal code itself: PROMPT_LIMIT, CADENCE_LIMIT, MONITOR_LIMIT, PAGE_LIMIT_EXCEEDED, SEAT_LIMIT_EXCEEDED, WORKSPACE_LIMIT_EXCEEDED, PLANNER_DISABLED, AUTO_EXECUTE_DISABLED, AGENT_SKILLS_NOT_ENTITLED, PAGE_TEMPLATES_NOT_ENTITLED, HOSTED_PAGES_NOT_ENTITLED, AI_ATTRIBUTION_NOT_ENTITLED, ZAPIER_NOT_ENTITLED, BYO_KEYS_NOT_ENTITLED, INCREMENTALITY_NOT_ENTITLED, WEBHOOKS_NOT_ENTITLED; `result` holds the tool refusal). Body carries upgrade_url (and reason, for tool refusals) where an upgrade is the fix. |
403 | The plan allows it but the key creator's role in the workspace does not (FORBIDDEN_ROLE; e.g. a creator now a viewer calling an acting tool). No upgrade fixes it: an admin changes the role. |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
409 | A request with this Idempotency-Key is still running (IDEMPOTENCY_IN_PROGRESS; repeat after Retry-After to collect the result), or it ran and its answer was too large to keep (IDEMPOTENCY_RESULT_NOT_KEPT; it is not run again). |
413 | Request body over 256 KB (BODY_TOO_LARGE). Tool arguments are small JSON objects. |
422 | The tool refused: it needs a confirmation step first (NEEDS_CONFIRMATION), or it declined for another reason it states (TOOL_REFUSED); result holds its explanation. Or this Idempotency-Key was used for a different tool or arguments (IDEMPOTENCY_KEY_REUSED). |
429 | Rate limited: the per-key tool-call limit (Retry-After header set), or the tool refused for a rate cap (e.g. ARTICLE_FAILURE_CAP; body carries the tool result). |
502 | Tool execution failed (TOOL_FAILED) |
503 | Temporarily unavailable, on our side, not a limit: the upstream data provider or the credit check is down (PROVIDER_UNAVAILABLE; nothing was charged), or idempotency is unavailable and the tool was NOT run (IDEMPOTENCY_UNAVAILABLE). Retry shortly. |
504 | The tool is still running past the 60s response ceiling and was not stopped (TOOL_TIMEOUT). With an Idempotency-Key, repeat the request to collect its answer. |
curl -X POST "https://app.seomatic.ai/api/v1/tools/get_query_pages" \
-H "Authorization: Bearer $SEOMATIC_API_KEY" \
-H "Content-Type: application/json" \
-d '{"queries":[]}'/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 answered. result is its output, usually a JSON string (parse it). A tool that refuses does NOT answer 200: it gets the matching 402/422/429/503 below, with its own output in result. |
400 | Invalid arguments (INVALID_ARGUMENTS; details says what) or a malformed Idempotency-Key (INVALID_IDEMPOTENCY_KEY). |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA); the plan does not include acting through the API (SCOPE_REVOKED_BY_PLAN); X-Seomatic-Client is n8n or make and the workspace has no paid plan or trial (AUTOMATION_NOT_ENTITLED); the free monthly question limit is reached (FREE_QUOTA_EXCEEDED; body carries keep_going_url and a question_pack payment link); the subscription is paused or its card was declined (BILLING_INACTIVE; body links the one step that restores it, never an upgrade); or the tool refused for credits (INSUFFICIENT_CREDITS, PAYMENT_REQUIRED; body carries the tool result); or the tool hit a plan limit (the code is the refusal code itself: PROMPT_LIMIT, CADENCE_LIMIT, MONITOR_LIMIT, PAGE_LIMIT_EXCEEDED, SEAT_LIMIT_EXCEEDED, WORKSPACE_LIMIT_EXCEEDED, PLANNER_DISABLED, AUTO_EXECUTE_DISABLED, AGENT_SKILLS_NOT_ENTITLED, PAGE_TEMPLATES_NOT_ENTITLED, HOSTED_PAGES_NOT_ENTITLED, AI_ATTRIBUTION_NOT_ENTITLED, ZAPIER_NOT_ENTITLED, BYO_KEYS_NOT_ENTITLED, INCREMENTALITY_NOT_ENTITLED, WEBHOOKS_NOT_ENTITLED; `result` holds the tool refusal). Body carries upgrade_url (and reason, for tool refusals) where an upgrade is the fix. |
403 | The plan allows it but the key creator's role in the workspace does not (FORBIDDEN_ROLE; e.g. a creator now a viewer calling an acting tool). No upgrade fixes it: an admin changes the role. |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
409 | A request with this Idempotency-Key is still running (IDEMPOTENCY_IN_PROGRESS; repeat after Retry-After to collect the result), or it ran and its answer was too large to keep (IDEMPOTENCY_RESULT_NOT_KEPT; it is not run again). |
413 | Request body over 256 KB (BODY_TOO_LARGE). Tool arguments are small JSON objects. |
422 | The tool refused: it needs a confirmation step first (NEEDS_CONFIRMATION), or it declined for another reason it states (TOOL_REFUSED); result holds its explanation. Or this Idempotency-Key was used for a different tool or arguments (IDEMPOTENCY_KEY_REUSED). |
429 | Rate limited: the per-key tool-call limit (Retry-After header set), or the tool refused for a rate cap (e.g. ARTICLE_FAILURE_CAP; body carries the tool result). |
502 | Tool execution failed (TOOL_FAILED) |
503 | Temporarily unavailable, on our side, not a limit: the upstream data provider or the credit check is down (PROVIDER_UNAVAILABLE; nothing was charged), or idempotency is unavailable and the tool was NOT run (IDEMPOTENCY_UNAVAILABLE). Retry shortly. |
504 | The tool is still running past the 60s response ceiling and was not stopped (TOOL_TIMEOUT). With an Idempotency-Key, repeat the request to collect its answer. |
curl -X POST "https://app.seomatic.ai/api/v1/tools/compare_periods" \
-H "Authorization: Bearer $SEOMATIC_API_KEY"/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 answered. result is its output, usually a JSON string (parse it). A tool that refuses does NOT answer 200: it gets the matching 402/422/429/503 below, with its own output in result. |
400 | Invalid arguments (INVALID_ARGUMENTS; details says what) or a malformed Idempotency-Key (INVALID_IDEMPOTENCY_KEY). |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA); the plan does not include acting through the API (SCOPE_REVOKED_BY_PLAN); X-Seomatic-Client is n8n or make and the workspace has no paid plan or trial (AUTOMATION_NOT_ENTITLED); the free monthly question limit is reached (FREE_QUOTA_EXCEEDED; body carries keep_going_url and a question_pack payment link); the subscription is paused or its card was declined (BILLING_INACTIVE; body links the one step that restores it, never an upgrade); or the tool refused for credits (INSUFFICIENT_CREDITS, PAYMENT_REQUIRED; body carries the tool result); or the tool hit a plan limit (the code is the refusal code itself: PROMPT_LIMIT, CADENCE_LIMIT, MONITOR_LIMIT, PAGE_LIMIT_EXCEEDED, SEAT_LIMIT_EXCEEDED, WORKSPACE_LIMIT_EXCEEDED, PLANNER_DISABLED, AUTO_EXECUTE_DISABLED, AGENT_SKILLS_NOT_ENTITLED, PAGE_TEMPLATES_NOT_ENTITLED, HOSTED_PAGES_NOT_ENTITLED, AI_ATTRIBUTION_NOT_ENTITLED, ZAPIER_NOT_ENTITLED, BYO_KEYS_NOT_ENTITLED, INCREMENTALITY_NOT_ENTITLED, WEBHOOKS_NOT_ENTITLED; `result` holds the tool refusal). Body carries upgrade_url (and reason, for tool refusals) where an upgrade is the fix. |
403 | The plan allows it but the key creator's role in the workspace does not (FORBIDDEN_ROLE; e.g. a creator now a viewer calling an acting tool). No upgrade fixes it: an admin changes the role. |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
409 | A request with this Idempotency-Key is still running (IDEMPOTENCY_IN_PROGRESS; repeat after Retry-After to collect the result), or it ran and its answer was too large to keep (IDEMPOTENCY_RESULT_NOT_KEPT; it is not run again). |
413 | Request body over 256 KB (BODY_TOO_LARGE). Tool arguments are small JSON objects. |
422 | The tool refused: it needs a confirmation step first (NEEDS_CONFIRMATION), or it declined for another reason it states (TOOL_REFUSED); result holds its explanation. Or this Idempotency-Key was used for a different tool or arguments (IDEMPOTENCY_KEY_REUSED). |
429 | Rate limited: the per-key tool-call limit (Retry-After header set), or the tool refused for a rate cap (e.g. ARTICLE_FAILURE_CAP; body carries the tool result). |
502 | Tool execution failed (TOOL_FAILED) |
503 | Temporarily unavailable, on our side, not a limit: the upstream data provider or the credit check is down (PROVIDER_UNAVAILABLE; nothing was charged), or idempotency is unavailable and the tool was NOT run (IDEMPOTENCY_UNAVAILABLE). Retry shortly. |
504 | The tool is still running past the 60s response ceiling and was not stopped (TOOL_TIMEOUT). With an Idempotency-Key, repeat the request to collect its answer. |
curl -X POST "https://app.seomatic.ai/api/v1/tools/get_performance_trend" \
-H "Authorization: Bearer $SEOMATIC_API_KEY"/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 answered. result is its output, usually a JSON string (parse it). A tool that refuses does NOT answer 200: it gets the matching 402/422/429/503 below, with its own output in result. |
400 | Invalid arguments (INVALID_ARGUMENTS; details says what) or a malformed Idempotency-Key (INVALID_IDEMPOTENCY_KEY). |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA); the plan does not include acting through the API (SCOPE_REVOKED_BY_PLAN); X-Seomatic-Client is n8n or make and the workspace has no paid plan or trial (AUTOMATION_NOT_ENTITLED); the free monthly question limit is reached (FREE_QUOTA_EXCEEDED; body carries keep_going_url and a question_pack payment link); the subscription is paused or its card was declined (BILLING_INACTIVE; body links the one step that restores it, never an upgrade); or the tool refused for credits (INSUFFICIENT_CREDITS, PAYMENT_REQUIRED; body carries the tool result); or the tool hit a plan limit (the code is the refusal code itself: PROMPT_LIMIT, CADENCE_LIMIT, MONITOR_LIMIT, PAGE_LIMIT_EXCEEDED, SEAT_LIMIT_EXCEEDED, WORKSPACE_LIMIT_EXCEEDED, PLANNER_DISABLED, AUTO_EXECUTE_DISABLED, AGENT_SKILLS_NOT_ENTITLED, PAGE_TEMPLATES_NOT_ENTITLED, HOSTED_PAGES_NOT_ENTITLED, AI_ATTRIBUTION_NOT_ENTITLED, ZAPIER_NOT_ENTITLED, BYO_KEYS_NOT_ENTITLED, INCREMENTALITY_NOT_ENTITLED, WEBHOOKS_NOT_ENTITLED; `result` holds the tool refusal). Body carries upgrade_url (and reason, for tool refusals) where an upgrade is the fix. |
403 | The plan allows it but the key creator's role in the workspace does not (FORBIDDEN_ROLE; e.g. a creator now a viewer calling an acting tool). No upgrade fixes it: an admin changes the role. |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
409 | A request with this Idempotency-Key is still running (IDEMPOTENCY_IN_PROGRESS; repeat after Retry-After to collect the result), or it ran and its answer was too large to keep (IDEMPOTENCY_RESULT_NOT_KEPT; it is not run again). |
413 | Request body over 256 KB (BODY_TOO_LARGE). Tool arguments are small JSON objects. |
422 | The tool refused: it needs a confirmation step first (NEEDS_CONFIRMATION), or it declined for another reason it states (TOOL_REFUSED); result holds its explanation. Or this Idempotency-Key was used for a different tool or arguments (IDEMPOTENCY_KEY_REUSED). |
429 | Rate limited: the per-key tool-call limit (Retry-After header set), or the tool refused for a rate cap (e.g. ARTICLE_FAILURE_CAP; body carries the tool result). |
502 | Tool execution failed (TOOL_FAILED) |
503 | Temporarily unavailable, on our side, not a limit: the upstream data provider or the credit check is down (PROVIDER_UNAVAILABLE; nothing was charged), or idempotency is unavailable and the tool was NOT run (IDEMPOTENCY_UNAVAILABLE). Retry shortly. |
504 | The tool is still running past the 60s response ceiling and was not stopped (TOOL_TIMEOUT). With an Idempotency-Key, repeat the request to collect its answer. |
curl -X POST "https://app.seomatic.ai/api/v1/tools/inspect_url_indexing" \
-H "Authorization: Bearer $SEOMATIC_API_KEY" \
-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 answered. result is its output, usually a JSON string (parse it). A tool that refuses does NOT answer 200: it gets the matching 402/422/429/503 below, with its own output in result. |
400 | Invalid arguments (INVALID_ARGUMENTS; details says what) or a malformed Idempotency-Key (INVALID_IDEMPOTENCY_KEY). |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA); the plan does not include acting through the API (SCOPE_REVOKED_BY_PLAN); X-Seomatic-Client is n8n or make and the workspace has no paid plan or trial (AUTOMATION_NOT_ENTITLED); the free monthly question limit is reached (FREE_QUOTA_EXCEEDED; body carries keep_going_url and a question_pack payment link); the subscription is paused or its card was declined (BILLING_INACTIVE; body links the one step that restores it, never an upgrade); or the tool refused for credits (INSUFFICIENT_CREDITS, PAYMENT_REQUIRED; body carries the tool result); or the tool hit a plan limit (the code is the refusal code itself: PROMPT_LIMIT, CADENCE_LIMIT, MONITOR_LIMIT, PAGE_LIMIT_EXCEEDED, SEAT_LIMIT_EXCEEDED, WORKSPACE_LIMIT_EXCEEDED, PLANNER_DISABLED, AUTO_EXECUTE_DISABLED, AGENT_SKILLS_NOT_ENTITLED, PAGE_TEMPLATES_NOT_ENTITLED, HOSTED_PAGES_NOT_ENTITLED, AI_ATTRIBUTION_NOT_ENTITLED, ZAPIER_NOT_ENTITLED, BYO_KEYS_NOT_ENTITLED, INCREMENTALITY_NOT_ENTITLED, WEBHOOKS_NOT_ENTITLED; `result` holds the tool refusal). Body carries upgrade_url (and reason, for tool refusals) where an upgrade is the fix. |
403 | The plan allows it but the key creator's role in the workspace does not (FORBIDDEN_ROLE; e.g. a creator now a viewer calling an acting tool). No upgrade fixes it: an admin changes the role. |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
409 | A request with this Idempotency-Key is still running (IDEMPOTENCY_IN_PROGRESS; repeat after Retry-After to collect the result), or it ran and its answer was too large to keep (IDEMPOTENCY_RESULT_NOT_KEPT; it is not run again). |
413 | Request body over 256 KB (BODY_TOO_LARGE). Tool arguments are small JSON objects. |
422 | The tool refused: it needs a confirmation step first (NEEDS_CONFIRMATION), or it declined for another reason it states (TOOL_REFUSED); result holds its explanation. Or this Idempotency-Key was used for a different tool or arguments (IDEMPOTENCY_KEY_REUSED). |
429 | Rate limited: the per-key tool-call limit (Retry-After header set), or the tool refused for a rate cap (e.g. ARTICLE_FAILURE_CAP; body carries the tool result). |
502 | Tool execution failed (TOOL_FAILED) |
503 | Temporarily unavailable, on our side, not a limit: the upstream data provider or the credit check is down (PROVIDER_UNAVAILABLE; nothing was charged), or idempotency is unavailable and the tool was NOT run (IDEMPOTENCY_UNAVAILABLE). Retry shortly. |
504 | The tool is still running past the 60s response ceiling and was not stopped (TOOL_TIMEOUT). With an Idempotency-Key, repeat the request to collect its answer. |
curl -X POST "https://app.seomatic.ai/api/v1/tools/batch_inspect_urls" \
-H "Authorization: Bearer $SEOMATIC_API_KEY" \
-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 answered. result is its output, usually a JSON string (parse it). A tool that refuses does NOT answer 200: it gets the matching 402/422/429/503 below, with its own output in result. |
400 | Invalid arguments (INVALID_ARGUMENTS; details says what) or a malformed Idempotency-Key (INVALID_IDEMPOTENCY_KEY). |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA); the plan does not include acting through the API (SCOPE_REVOKED_BY_PLAN); X-Seomatic-Client is n8n or make and the workspace has no paid plan or trial (AUTOMATION_NOT_ENTITLED); the free monthly question limit is reached (FREE_QUOTA_EXCEEDED; body carries keep_going_url and a question_pack payment link); the subscription is paused or its card was declined (BILLING_INACTIVE; body links the one step that restores it, never an upgrade); or the tool refused for credits (INSUFFICIENT_CREDITS, PAYMENT_REQUIRED; body carries the tool result); or the tool hit a plan limit (the code is the refusal code itself: PROMPT_LIMIT, CADENCE_LIMIT, MONITOR_LIMIT, PAGE_LIMIT_EXCEEDED, SEAT_LIMIT_EXCEEDED, WORKSPACE_LIMIT_EXCEEDED, PLANNER_DISABLED, AUTO_EXECUTE_DISABLED, AGENT_SKILLS_NOT_ENTITLED, PAGE_TEMPLATES_NOT_ENTITLED, HOSTED_PAGES_NOT_ENTITLED, AI_ATTRIBUTION_NOT_ENTITLED, ZAPIER_NOT_ENTITLED, BYO_KEYS_NOT_ENTITLED, INCREMENTALITY_NOT_ENTITLED, WEBHOOKS_NOT_ENTITLED; `result` holds the tool refusal). Body carries upgrade_url (and reason, for tool refusals) where an upgrade is the fix. |
403 | The plan allows it but the key creator's role in the workspace does not (FORBIDDEN_ROLE; e.g. a creator now a viewer calling an acting tool). No upgrade fixes it: an admin changes the role. |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
409 | A request with this Idempotency-Key is still running (IDEMPOTENCY_IN_PROGRESS; repeat after Retry-After to collect the result), or it ran and its answer was too large to keep (IDEMPOTENCY_RESULT_NOT_KEPT; it is not run again). |
413 | Request body over 256 KB (BODY_TOO_LARGE). Tool arguments are small JSON objects. |
422 | The tool refused: it needs a confirmation step first (NEEDS_CONFIRMATION), or it declined for another reason it states (TOOL_REFUSED); result holds its explanation. Or this Idempotency-Key was used for a different tool or arguments (IDEMPOTENCY_KEY_REUSED). |
429 | Rate limited: the per-key tool-call limit (Retry-After header set), or the tool refused for a rate cap (e.g. ARTICLE_FAILURE_CAP; body carries the tool result). |
502 | Tool execution failed (TOOL_FAILED) |
503 | Temporarily unavailable, on our side, not a limit: the upstream data provider or the credit check is down (PROVIDER_UNAVAILABLE; nothing was charged), or idempotency is unavailable and the tool was NOT run (IDEMPOTENCY_UNAVAILABLE). Retry shortly. |
504 | The tool is still running past the 60s response ceiling and was not stopped (TOOL_TIMEOUT). With an Idempotency-Key, repeat the request to collect its answer. |
curl -X POST "https://app.seomatic.ai/api/v1/tools/find_cannibalization" \
-H "Authorization: Bearer $SEOMATIC_API_KEY"/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 answered. result is its output, usually a JSON string (parse it). A tool that refuses does NOT answer 200: it gets the matching 402/422/429/503 below, with its own output in result. |
400 | Invalid arguments (INVALID_ARGUMENTS; details says what) or a malformed Idempotency-Key (INVALID_IDEMPOTENCY_KEY). |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA); the plan does not include acting through the API (SCOPE_REVOKED_BY_PLAN); X-Seomatic-Client is n8n or make and the workspace has no paid plan or trial (AUTOMATION_NOT_ENTITLED); the free monthly question limit is reached (FREE_QUOTA_EXCEEDED; body carries keep_going_url and a question_pack payment link); the subscription is paused or its card was declined (BILLING_INACTIVE; body links the one step that restores it, never an upgrade); or the tool refused for credits (INSUFFICIENT_CREDITS, PAYMENT_REQUIRED; body carries the tool result); or the tool hit a plan limit (the code is the refusal code itself: PROMPT_LIMIT, CADENCE_LIMIT, MONITOR_LIMIT, PAGE_LIMIT_EXCEEDED, SEAT_LIMIT_EXCEEDED, WORKSPACE_LIMIT_EXCEEDED, PLANNER_DISABLED, AUTO_EXECUTE_DISABLED, AGENT_SKILLS_NOT_ENTITLED, PAGE_TEMPLATES_NOT_ENTITLED, HOSTED_PAGES_NOT_ENTITLED, AI_ATTRIBUTION_NOT_ENTITLED, ZAPIER_NOT_ENTITLED, BYO_KEYS_NOT_ENTITLED, INCREMENTALITY_NOT_ENTITLED, WEBHOOKS_NOT_ENTITLED; `result` holds the tool refusal). Body carries upgrade_url (and reason, for tool refusals) where an upgrade is the fix. |
403 | The plan allows it but the key creator's role in the workspace does not (FORBIDDEN_ROLE; e.g. a creator now a viewer calling an acting tool). No upgrade fixes it: an admin changes the role. |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
409 | A request with this Idempotency-Key is still running (IDEMPOTENCY_IN_PROGRESS; repeat after Retry-After to collect the result), or it ran and its answer was too large to keep (IDEMPOTENCY_RESULT_NOT_KEPT; it is not run again). |
413 | Request body over 256 KB (BODY_TOO_LARGE). Tool arguments are small JSON objects. |
422 | The tool refused: it needs a confirmation step first (NEEDS_CONFIRMATION), or it declined for another reason it states (TOOL_REFUSED); result holds its explanation. Or this Idempotency-Key was used for a different tool or arguments (IDEMPOTENCY_KEY_REUSED). |
429 | Rate limited: the per-key tool-call limit (Retry-After header set), or the tool refused for a rate cap (e.g. ARTICLE_FAILURE_CAP; body carries the tool result). |
502 | Tool execution failed (TOOL_FAILED) |
503 | Temporarily unavailable, on our side, not a limit: the upstream data provider or the credit check is down (PROVIDER_UNAVAILABLE; nothing was charged), or idempotency is unavailable and the tool was NOT run (IDEMPOTENCY_UNAVAILABLE). Retry shortly. |
504 | The tool is still running past the 60s response ceiling and was not stopped (TOOL_TIMEOUT). With an Idempotency-Key, repeat the request to collect its answer. |
curl -X POST "https://app.seomatic.ai/api/v1/tools/get_brand_split" \
-H "Authorization: Bearer $SEOMATIC_API_KEY"/tools/find_ctr_outliersreadFind pages whose click-through rate is far below what their position should earn, against the expected CTR for their position (the same curve every SEOmatic answer uses; brand queries excluded, since…
| 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 answered. result is its output, usually a JSON string (parse it). A tool that refuses does NOT answer 200: it gets the matching 402/422/429/503 below, with its own output in result. |
400 | Invalid arguments (INVALID_ARGUMENTS; details says what) or a malformed Idempotency-Key (INVALID_IDEMPOTENCY_KEY). |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA); the plan does not include acting through the API (SCOPE_REVOKED_BY_PLAN); X-Seomatic-Client is n8n or make and the workspace has no paid plan or trial (AUTOMATION_NOT_ENTITLED); the free monthly question limit is reached (FREE_QUOTA_EXCEEDED; body carries keep_going_url and a question_pack payment link); the subscription is paused or its card was declined (BILLING_INACTIVE; body links the one step that restores it, never an upgrade); or the tool refused for credits (INSUFFICIENT_CREDITS, PAYMENT_REQUIRED; body carries the tool result); or the tool hit a plan limit (the code is the refusal code itself: PROMPT_LIMIT, CADENCE_LIMIT, MONITOR_LIMIT, PAGE_LIMIT_EXCEEDED, SEAT_LIMIT_EXCEEDED, WORKSPACE_LIMIT_EXCEEDED, PLANNER_DISABLED, AUTO_EXECUTE_DISABLED, AGENT_SKILLS_NOT_ENTITLED, PAGE_TEMPLATES_NOT_ENTITLED, HOSTED_PAGES_NOT_ENTITLED, AI_ATTRIBUTION_NOT_ENTITLED, ZAPIER_NOT_ENTITLED, BYO_KEYS_NOT_ENTITLED, INCREMENTALITY_NOT_ENTITLED, WEBHOOKS_NOT_ENTITLED; `result` holds the tool refusal). Body carries upgrade_url (and reason, for tool refusals) where an upgrade is the fix. |
403 | The plan allows it but the key creator's role in the workspace does not (FORBIDDEN_ROLE; e.g. a creator now a viewer calling an acting tool). No upgrade fixes it: an admin changes the role. |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
409 | A request with this Idempotency-Key is still running (IDEMPOTENCY_IN_PROGRESS; repeat after Retry-After to collect the result), or it ran and its answer was too large to keep (IDEMPOTENCY_RESULT_NOT_KEPT; it is not run again). |
413 | Request body over 256 KB (BODY_TOO_LARGE). Tool arguments are small JSON objects. |
422 | The tool refused: it needs a confirmation step first (NEEDS_CONFIRMATION), or it declined for another reason it states (TOOL_REFUSED); result holds its explanation. Or this Idempotency-Key was used for a different tool or arguments (IDEMPOTENCY_KEY_REUSED). |
429 | Rate limited: the per-key tool-call limit (Retry-After header set), or the tool refused for a rate cap (e.g. ARTICLE_FAILURE_CAP; body carries the tool result). |
502 | Tool execution failed (TOOL_FAILED) |
503 | Temporarily unavailable, on our side, not a limit: the upstream data provider or the credit check is down (PROVIDER_UNAVAILABLE; nothing was charged), or idempotency is unavailable and the tool was NOT run (IDEMPOTENCY_UNAVAILABLE). Retry shortly. |
504 | The tool is still running past the 60s response ceiling and was not stopped (TOOL_TIMEOUT). With an Idempotency-Key, repeat the request to collect its answer. |
curl -X POST "https://app.seomatic.ai/api/v1/tools/find_ctr_outliers" \
-H "Authorization: Bearer $SEOMATIC_API_KEY"/tools/get_search_appearancereadBreak performance down by search appearance (rich results, videos, product snippets, review stars...). Shows which enhanced results you already earn and how they convert vs plain listings - the case…
| Name | Type | Required | Description |
|---|---|---|---|
days | number | no |
| Status | Description |
|---|---|
200 | { tool, result }: the tool answered. result is its output, usually a JSON string (parse it). A tool that refuses does NOT answer 200: it gets the matching 402/422/429/503 below, with its own output in result. |
400 | Invalid arguments (INVALID_ARGUMENTS; details says what) or a malformed Idempotency-Key (INVALID_IDEMPOTENCY_KEY). |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA); the plan does not include acting through the API (SCOPE_REVOKED_BY_PLAN); X-Seomatic-Client is n8n or make and the workspace has no paid plan or trial (AUTOMATION_NOT_ENTITLED); the free monthly question limit is reached (FREE_QUOTA_EXCEEDED; body carries keep_going_url and a question_pack payment link); the subscription is paused or its card was declined (BILLING_INACTIVE; body links the one step that restores it, never an upgrade); or the tool refused for credits (INSUFFICIENT_CREDITS, PAYMENT_REQUIRED; body carries the tool result); or the tool hit a plan limit (the code is the refusal code itself: PROMPT_LIMIT, CADENCE_LIMIT, MONITOR_LIMIT, PAGE_LIMIT_EXCEEDED, SEAT_LIMIT_EXCEEDED, WORKSPACE_LIMIT_EXCEEDED, PLANNER_DISABLED, AUTO_EXECUTE_DISABLED, AGENT_SKILLS_NOT_ENTITLED, PAGE_TEMPLATES_NOT_ENTITLED, HOSTED_PAGES_NOT_ENTITLED, AI_ATTRIBUTION_NOT_ENTITLED, ZAPIER_NOT_ENTITLED, BYO_KEYS_NOT_ENTITLED, INCREMENTALITY_NOT_ENTITLED, WEBHOOKS_NOT_ENTITLED; `result` holds the tool refusal). Body carries upgrade_url (and reason, for tool refusals) where an upgrade is the fix. |
403 | The plan allows it but the key creator's role in the workspace does not (FORBIDDEN_ROLE; e.g. a creator now a viewer calling an acting tool). No upgrade fixes it: an admin changes the role. |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
409 | A request with this Idempotency-Key is still running (IDEMPOTENCY_IN_PROGRESS; repeat after Retry-After to collect the result), or it ran and its answer was too large to keep (IDEMPOTENCY_RESULT_NOT_KEPT; it is not run again). |
413 | Request body over 256 KB (BODY_TOO_LARGE). Tool arguments are small JSON objects. |
422 | The tool refused: it needs a confirmation step first (NEEDS_CONFIRMATION), or it declined for another reason it states (TOOL_REFUSED); result holds its explanation. Or this Idempotency-Key was used for a different tool or arguments (IDEMPOTENCY_KEY_REUSED). |
429 | Rate limited: the per-key tool-call limit (Retry-After header set), or the tool refused for a rate cap (e.g. ARTICLE_FAILURE_CAP; body carries the tool result). |
502 | Tool execution failed (TOOL_FAILED) |
503 | Temporarily unavailable, on our side, not a limit: the upstream data provider or the credit check is down (PROVIDER_UNAVAILABLE; nothing was charged), or idempotency is unavailable and the tool was NOT run (IDEMPOTENCY_UNAVAILABLE). Retry shortly. |
504 | The tool is still running past the 60s response ceiling and was not stopped (TOOL_TIMEOUT). With an Idempotency-Key, repeat the request to collect its answer. |
curl -X POST "https://app.seomatic.ai/api/v1/tools/get_search_appearance" \
-H "Authorization: Bearer $SEOMATIC_API_KEY"/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 answered. result is its output, usually a JSON string (parse it). A tool that refuses does NOT answer 200: it gets the matching 402/422/429/503 below, with its own output in result. |
400 | Invalid arguments (INVALID_ARGUMENTS; details says what) or a malformed Idempotency-Key (INVALID_IDEMPOTENCY_KEY). |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA); the plan does not include acting through the API (SCOPE_REVOKED_BY_PLAN); X-Seomatic-Client is n8n or make and the workspace has no paid plan or trial (AUTOMATION_NOT_ENTITLED); the free monthly question limit is reached (FREE_QUOTA_EXCEEDED; body carries keep_going_url and a question_pack payment link); the subscription is paused or its card was declined (BILLING_INACTIVE; body links the one step that restores it, never an upgrade); or the tool refused for credits (INSUFFICIENT_CREDITS, PAYMENT_REQUIRED; body carries the tool result); or the tool hit a plan limit (the code is the refusal code itself: PROMPT_LIMIT, CADENCE_LIMIT, MONITOR_LIMIT, PAGE_LIMIT_EXCEEDED, SEAT_LIMIT_EXCEEDED, WORKSPACE_LIMIT_EXCEEDED, PLANNER_DISABLED, AUTO_EXECUTE_DISABLED, AGENT_SKILLS_NOT_ENTITLED, PAGE_TEMPLATES_NOT_ENTITLED, HOSTED_PAGES_NOT_ENTITLED, AI_ATTRIBUTION_NOT_ENTITLED, ZAPIER_NOT_ENTITLED, BYO_KEYS_NOT_ENTITLED, INCREMENTALITY_NOT_ENTITLED, WEBHOOKS_NOT_ENTITLED; `result` holds the tool refusal). Body carries upgrade_url (and reason, for tool refusals) where an upgrade is the fix. |
403 | The plan allows it but the key creator's role in the workspace does not (FORBIDDEN_ROLE; e.g. a creator now a viewer calling an acting tool). No upgrade fixes it: an admin changes the role. |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
409 | A request with this Idempotency-Key is still running (IDEMPOTENCY_IN_PROGRESS; repeat after Retry-After to collect the result), or it ran and its answer was too large to keep (IDEMPOTENCY_RESULT_NOT_KEPT; it is not run again). |
413 | Request body over 256 KB (BODY_TOO_LARGE). Tool arguments are small JSON objects. |
422 | The tool refused: it needs a confirmation step first (NEEDS_CONFIRMATION), or it declined for another reason it states (TOOL_REFUSED); result holds its explanation. Or this Idempotency-Key was used for a different tool or arguments (IDEMPOTENCY_KEY_REUSED). |
429 | Rate limited: the per-key tool-call limit (Retry-After header set), or the tool refused for a rate cap (e.g. ARTICLE_FAILURE_CAP; body carries the tool result). |
502 | Tool execution failed (TOOL_FAILED) |
503 | Temporarily unavailable, on our side, not a limit: the upstream data provider or the credit check is down (PROVIDER_UNAVAILABLE; nothing was charged), or idempotency is unavailable and the tool was NOT run (IDEMPOTENCY_UNAVAILABLE). Retry shortly. |
504 | The tool is still running past the 60s response ceiling and was not stopped (TOOL_TIMEOUT). With an Idempotency-Key, repeat the request to collect its answer. |
curl -X POST "https://app.seomatic.ai/api/v1/tools/get_seasonality_baseline" \
-H "Authorization: Bearer $SEOMATIC_API_KEY"/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 answered. result is its output, usually a JSON string (parse it). A tool that refuses does NOT answer 200: it gets the matching 402/422/429/503 below, with its own output in result. |
400 | Invalid arguments (INVALID_ARGUMENTS; details says what) or a malformed Idempotency-Key (INVALID_IDEMPOTENCY_KEY). |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA); the plan does not include acting through the API (SCOPE_REVOKED_BY_PLAN); X-Seomatic-Client is n8n or make and the workspace has no paid plan or trial (AUTOMATION_NOT_ENTITLED); the free monthly question limit is reached (FREE_QUOTA_EXCEEDED; body carries keep_going_url and a question_pack payment link); the subscription is paused or its card was declined (BILLING_INACTIVE; body links the one step that restores it, never an upgrade); or the tool refused for credits (INSUFFICIENT_CREDITS, PAYMENT_REQUIRED; body carries the tool result); or the tool hit a plan limit (the code is the refusal code itself: PROMPT_LIMIT, CADENCE_LIMIT, MONITOR_LIMIT, PAGE_LIMIT_EXCEEDED, SEAT_LIMIT_EXCEEDED, WORKSPACE_LIMIT_EXCEEDED, PLANNER_DISABLED, AUTO_EXECUTE_DISABLED, AGENT_SKILLS_NOT_ENTITLED, PAGE_TEMPLATES_NOT_ENTITLED, HOSTED_PAGES_NOT_ENTITLED, AI_ATTRIBUTION_NOT_ENTITLED, ZAPIER_NOT_ENTITLED, BYO_KEYS_NOT_ENTITLED, INCREMENTALITY_NOT_ENTITLED, WEBHOOKS_NOT_ENTITLED; `result` holds the tool refusal). Body carries upgrade_url (and reason, for tool refusals) where an upgrade is the fix. |
403 | The plan allows it but the key creator's role in the workspace does not (FORBIDDEN_ROLE; e.g. a creator now a viewer calling an acting tool). No upgrade fixes it: an admin changes the role. |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
409 | A request with this Idempotency-Key is still running (IDEMPOTENCY_IN_PROGRESS; repeat after Retry-After to collect the result), or it ran and its answer was too large to keep (IDEMPOTENCY_RESULT_NOT_KEPT; it is not run again). |
413 | Request body over 256 KB (BODY_TOO_LARGE). Tool arguments are small JSON objects. |
422 | The tool refused: it needs a confirmation step first (NEEDS_CONFIRMATION), or it declined for another reason it states (TOOL_REFUSED); result holds its explanation. Or this Idempotency-Key was used for a different tool or arguments (IDEMPOTENCY_KEY_REUSED). |
429 | Rate limited: the per-key tool-call limit (Retry-After header set), or the tool refused for a rate cap (e.g. ARTICLE_FAILURE_CAP; body carries the tool result). |
502 | Tool execution failed (TOOL_FAILED) |
503 | Temporarily unavailable, on our side, not a limit: the upstream data provider or the credit check is down (PROVIDER_UNAVAILABLE; nothing was charged), or idempotency is unavailable and the tool was NOT run (IDEMPOTENCY_UNAVAILABLE). Retry shortly. |
504 | The tool is still running past the 60s response ceiling and was not stopped (TOOL_TIMEOUT). With an Idempotency-Key, repeat the request to collect its answer. |
curl -X POST "https://app.seomatic.ai/api/v1/tools/get_sitemaps_status" \
-H "Authorization: Bearer $SEOMATIC_API_KEY"/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 answered. result is its output, usually a JSON string (parse it). A tool that refuses does NOT answer 200: it gets the matching 402/422/429/503 below, with its own output in result. |
400 | Invalid arguments (INVALID_ARGUMENTS; details says what) or a malformed Idempotency-Key (INVALID_IDEMPOTENCY_KEY). |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA); the plan does not include acting through the API (SCOPE_REVOKED_BY_PLAN); X-Seomatic-Client is n8n or make and the workspace has no paid plan or trial (AUTOMATION_NOT_ENTITLED); the free monthly question limit is reached (FREE_QUOTA_EXCEEDED; body carries keep_going_url and a question_pack payment link); the subscription is paused or its card was declined (BILLING_INACTIVE; body links the one step that restores it, never an upgrade); or the tool refused for credits (INSUFFICIENT_CREDITS, PAYMENT_REQUIRED; body carries the tool result); or the tool hit a plan limit (the code is the refusal code itself: PROMPT_LIMIT, CADENCE_LIMIT, MONITOR_LIMIT, PAGE_LIMIT_EXCEEDED, SEAT_LIMIT_EXCEEDED, WORKSPACE_LIMIT_EXCEEDED, PLANNER_DISABLED, AUTO_EXECUTE_DISABLED, AGENT_SKILLS_NOT_ENTITLED, PAGE_TEMPLATES_NOT_ENTITLED, HOSTED_PAGES_NOT_ENTITLED, AI_ATTRIBUTION_NOT_ENTITLED, ZAPIER_NOT_ENTITLED, BYO_KEYS_NOT_ENTITLED, INCREMENTALITY_NOT_ENTITLED, WEBHOOKS_NOT_ENTITLED; `result` holds the tool refusal). Body carries upgrade_url (and reason, for tool refusals) where an upgrade is the fix. |
403 | The plan allows it but the key creator's role in the workspace does not (FORBIDDEN_ROLE; e.g. a creator now a viewer calling an acting tool). No upgrade fixes it: an admin changes the role. |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
409 | A request with this Idempotency-Key is still running (IDEMPOTENCY_IN_PROGRESS; repeat after Retry-After to collect the result), or it ran and its answer was too large to keep (IDEMPOTENCY_RESULT_NOT_KEPT; it is not run again). |
413 | Request body over 256 KB (BODY_TOO_LARGE). Tool arguments are small JSON objects. |
422 | The tool refused: it needs a confirmation step first (NEEDS_CONFIRMATION), or it declined for another reason it states (TOOL_REFUSED); result holds its explanation. Or this Idempotency-Key was used for a different tool or arguments (IDEMPOTENCY_KEY_REUSED). |
429 | Rate limited: the per-key tool-call limit (Retry-After header set), or the tool refused for a rate cap (e.g. ARTICLE_FAILURE_CAP; body carries the tool result). |
502 | Tool execution failed (TOOL_FAILED) |
503 | Temporarily unavailable, on our side, not a limit: the upstream data provider or the credit check is down (PROVIDER_UNAVAILABLE; nothing was charged), or idempotency is unavailable and the tool was NOT run (IDEMPOTENCY_UNAVAILABLE). Retry shortly. |
504 | The tool is still running past the 60s response ceiling and was not stopped (TOOL_TIMEOUT). With an Idempotency-Key, repeat the request to collect its answer. |
curl -X POST "https://app.seomatic.ai/api/v1/tools/get_discover_news_performance" \
-H "Authorization: Bearer $SEOMATIC_API_KEY"/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 answered. result is its output, usually a JSON string (parse it). A tool that refuses does NOT answer 200: it gets the matching 402/422/429/503 below, with its own output in result. |
400 | Invalid arguments (INVALID_ARGUMENTS; details says what) or a malformed Idempotency-Key (INVALID_IDEMPOTENCY_KEY). |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA); the plan does not include acting through the API (SCOPE_REVOKED_BY_PLAN); X-Seomatic-Client is n8n or make and the workspace has no paid plan or trial (AUTOMATION_NOT_ENTITLED); the free monthly question limit is reached (FREE_QUOTA_EXCEEDED; body carries keep_going_url and a question_pack payment link); the subscription is paused or its card was declined (BILLING_INACTIVE; body links the one step that restores it, never an upgrade); or the tool refused for credits (INSUFFICIENT_CREDITS, PAYMENT_REQUIRED; body carries the tool result); or the tool hit a plan limit (the code is the refusal code itself: PROMPT_LIMIT, CADENCE_LIMIT, MONITOR_LIMIT, PAGE_LIMIT_EXCEEDED, SEAT_LIMIT_EXCEEDED, WORKSPACE_LIMIT_EXCEEDED, PLANNER_DISABLED, AUTO_EXECUTE_DISABLED, AGENT_SKILLS_NOT_ENTITLED, PAGE_TEMPLATES_NOT_ENTITLED, HOSTED_PAGES_NOT_ENTITLED, AI_ATTRIBUTION_NOT_ENTITLED, ZAPIER_NOT_ENTITLED, BYO_KEYS_NOT_ENTITLED, INCREMENTALITY_NOT_ENTITLED, WEBHOOKS_NOT_ENTITLED; `result` holds the tool refusal). Body carries upgrade_url (and reason, for tool refusals) where an upgrade is the fix. |
403 | The plan allows it but the key creator's role in the workspace does not (FORBIDDEN_ROLE; e.g. a creator now a viewer calling an acting tool). No upgrade fixes it: an admin changes the role. |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
409 | A request with this Idempotency-Key is still running (IDEMPOTENCY_IN_PROGRESS; repeat after Retry-After to collect the result), or it ran and its answer was too large to keep (IDEMPOTENCY_RESULT_NOT_KEPT; it is not run again). |
413 | Request body over 256 KB (BODY_TOO_LARGE). Tool arguments are small JSON objects. |
422 | The tool refused: it needs a confirmation step first (NEEDS_CONFIRMATION), or it declined for another reason it states (TOOL_REFUSED); result holds its explanation. Or this Idempotency-Key was used for a different tool or arguments (IDEMPOTENCY_KEY_REUSED). |
429 | Rate limited: the per-key tool-call limit (Retry-After header set), or the tool refused for a rate cap (e.g. ARTICLE_FAILURE_CAP; body carries the tool result). |
502 | Tool execution failed (TOOL_FAILED) |
503 | Temporarily unavailable, on our side, not a limit: the upstream data provider or the credit check is down (PROVIDER_UNAVAILABLE; nothing was charged), or idempotency is unavailable and the tool was NOT run (IDEMPOTENCY_UNAVAILABLE). Retry shortly. |
504 | The tool is still running past the 60s response ceiling and was not stopped (TOOL_TIMEOUT). With an Idempotency-Key, repeat the request to collect its answer. |
curl -X POST "https://app.seomatic.ai/api/v1/tools/get_folder_performance" \
-H "Authorization: Bearer $SEOMATIC_API_KEY"/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 answered. result is its output, usually a JSON string (parse it). A tool that refuses does NOT answer 200: it gets the matching 402/422/429/503 below, with its own output in result. |
400 | Invalid arguments (INVALID_ARGUMENTS; details says what) or a malformed Idempotency-Key (INVALID_IDEMPOTENCY_KEY). |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA); the plan does not include acting through the API (SCOPE_REVOKED_BY_PLAN); X-Seomatic-Client is n8n or make and the workspace has no paid plan or trial (AUTOMATION_NOT_ENTITLED); the free monthly question limit is reached (FREE_QUOTA_EXCEEDED; body carries keep_going_url and a question_pack payment link); the subscription is paused or its card was declined (BILLING_INACTIVE; body links the one step that restores it, never an upgrade); or the tool refused for credits (INSUFFICIENT_CREDITS, PAYMENT_REQUIRED; body carries the tool result); or the tool hit a plan limit (the code is the refusal code itself: PROMPT_LIMIT, CADENCE_LIMIT, MONITOR_LIMIT, PAGE_LIMIT_EXCEEDED, SEAT_LIMIT_EXCEEDED, WORKSPACE_LIMIT_EXCEEDED, PLANNER_DISABLED, AUTO_EXECUTE_DISABLED, AGENT_SKILLS_NOT_ENTITLED, PAGE_TEMPLATES_NOT_ENTITLED, HOSTED_PAGES_NOT_ENTITLED, AI_ATTRIBUTION_NOT_ENTITLED, ZAPIER_NOT_ENTITLED, BYO_KEYS_NOT_ENTITLED, INCREMENTALITY_NOT_ENTITLED, WEBHOOKS_NOT_ENTITLED; `result` holds the tool refusal). Body carries upgrade_url (and reason, for tool refusals) where an upgrade is the fix. |
403 | The plan allows it but the key creator's role in the workspace does not (FORBIDDEN_ROLE; e.g. a creator now a viewer calling an acting tool). No upgrade fixes it: an admin changes the role. |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
409 | A request with this Idempotency-Key is still running (IDEMPOTENCY_IN_PROGRESS; repeat after Retry-After to collect the result), or it ran and its answer was too large to keep (IDEMPOTENCY_RESULT_NOT_KEPT; it is not run again). |
413 | Request body over 256 KB (BODY_TOO_LARGE). Tool arguments are small JSON objects. |
422 | The tool refused: it needs a confirmation step first (NEEDS_CONFIRMATION), or it declined for another reason it states (TOOL_REFUSED); result holds its explanation. Or this Idempotency-Key was used for a different tool or arguments (IDEMPOTENCY_KEY_REUSED). |
429 | Rate limited: the per-key tool-call limit (Retry-After header set), or the tool refused for a rate cap (e.g. ARTICLE_FAILURE_CAP; body carries the tool result). |
502 | Tool execution failed (TOOL_FAILED) |
503 | Temporarily unavailable, on our side, not a limit: the upstream data provider or the credit check is down (PROVIDER_UNAVAILABLE; nothing was charged), or idempotency is unavailable and the tool was NOT run (IDEMPOTENCY_UNAVAILABLE). Retry shortly. |
504 | The tool is still running past the 60s response ceiling and was not stopped (TOOL_TIMEOUT). With an Idempotency-Key, repeat the request to collect its answer. |
curl -X POST "https://app.seomatic.ai/api/v1/tools/get_fresh_performance" \
-H "Authorization: Bearer $SEOMATIC_API_KEY"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.
First-party moat data from the workspace's own rollups. 'fetches' counts retrieval/indexing-class AI answer-crawler hits (the step that precedes a citation); 'referrals' counts visits an AI assistant sent back. This is the AI channel ordinary analytics files as Direct. Counts only.
| 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 $SEOMATIC_API_KEY"/brand-factsStore the workspace's canonical business facts as AI ground truth.
The owner's own declared business facts (name, founding year, contact, official profiles), used to detect AI answers that contradict them. One row per workspace, latest wins. Never page content or visitor data; keys outside the allowlist are dropped and each value is length-bounded.
| 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 $SEOMATIC_API_KEY"/tools/get_ai_visibilityreadRead the workspace's latest completed AI-search visibility scan: per-engine brand visibility (ChatGPT, Claude and Google AI Overviews by default, plus any engine the monitor tracks: Perplexity, Googl…
| 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 answered. result is its output, usually a JSON string (parse it). A tool that refuses does NOT answer 200: it gets the matching 402/422/429/503 below, with its own output in result. |
400 | Invalid arguments (INVALID_ARGUMENTS; details says what) or a malformed Idempotency-Key (INVALID_IDEMPOTENCY_KEY). |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA); the plan does not include acting through the API (SCOPE_REVOKED_BY_PLAN); X-Seomatic-Client is n8n or make and the workspace has no paid plan or trial (AUTOMATION_NOT_ENTITLED); the free monthly question limit is reached (FREE_QUOTA_EXCEEDED; body carries keep_going_url and a question_pack payment link); the subscription is paused or its card was declined (BILLING_INACTIVE; body links the one step that restores it, never an upgrade); or the tool refused for credits (INSUFFICIENT_CREDITS, PAYMENT_REQUIRED; body carries the tool result); or the tool hit a plan limit (the code is the refusal code itself: PROMPT_LIMIT, CADENCE_LIMIT, MONITOR_LIMIT, PAGE_LIMIT_EXCEEDED, SEAT_LIMIT_EXCEEDED, WORKSPACE_LIMIT_EXCEEDED, PLANNER_DISABLED, AUTO_EXECUTE_DISABLED, AGENT_SKILLS_NOT_ENTITLED, PAGE_TEMPLATES_NOT_ENTITLED, HOSTED_PAGES_NOT_ENTITLED, AI_ATTRIBUTION_NOT_ENTITLED, ZAPIER_NOT_ENTITLED, BYO_KEYS_NOT_ENTITLED, INCREMENTALITY_NOT_ENTITLED, WEBHOOKS_NOT_ENTITLED; `result` holds the tool refusal). Body carries upgrade_url (and reason, for tool refusals) where an upgrade is the fix. |
403 | The plan allows it but the key creator's role in the workspace does not (FORBIDDEN_ROLE; e.g. a creator now a viewer calling an acting tool). No upgrade fixes it: an admin changes the role. |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
409 | A request with this Idempotency-Key is still running (IDEMPOTENCY_IN_PROGRESS; repeat after Retry-After to collect the result), or it ran and its answer was too large to keep (IDEMPOTENCY_RESULT_NOT_KEPT; it is not run again). |
413 | Request body over 256 KB (BODY_TOO_LARGE). Tool arguments are small JSON objects. |
422 | The tool refused: it needs a confirmation step first (NEEDS_CONFIRMATION), or it declined for another reason it states (TOOL_REFUSED); result holds its explanation. Or this Idempotency-Key was used for a different tool or arguments (IDEMPOTENCY_KEY_REUSED). |
429 | Rate limited: the per-key tool-call limit (Retry-After header set), or the tool refused for a rate cap (e.g. ARTICLE_FAILURE_CAP; body carries the tool result). |
502 | Tool execution failed (TOOL_FAILED) |
503 | Temporarily unavailable, on our side, not a limit: the upstream data provider or the credit check is down (PROVIDER_UNAVAILABLE; nothing was charged), or idempotency is unavailable and the tool was NOT run (IDEMPOTENCY_UNAVAILABLE). Retry shortly. |
504 | The tool is still running past the 60s response ceiling and was not stopped (TOOL_TIMEOUT). With an Idempotency-Key, repeat the request to collect its answer. |
curl -X POST "https://app.seomatic.ai/api/v1/tools/get_ai_visibility" \
-H "Authorization: Bearer $SEOMATIC_API_KEY"/tools/run_ai_visibility_scanactsStart a fresh AI-search visibility scan: queries the live AI engines (ChatGPT, Claude and Google AI Overviews by default, plus any the monitor switched on, such as Perplexity) with buyer-intent promp…
| 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. |
is_my_site | boolean | no | Only when the workspace has no site on record yet: true if the domain is the user's own site, false if it is a competit… |
| Status | Description |
|---|---|
200 | { tool, result }: the tool answered. result is its output, usually a JSON string (parse it). A tool that refuses does NOT answer 200: it gets the matching 402/422/429/503 below, with its own output in result. |
400 | Invalid arguments (INVALID_ARGUMENTS; details says what) or a malformed Idempotency-Key (INVALID_IDEMPOTENCY_KEY). |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA); the plan does not include acting through the API (SCOPE_REVOKED_BY_PLAN); X-Seomatic-Client is n8n or make and the workspace has no paid plan or trial (AUTOMATION_NOT_ENTITLED); the free monthly question limit is reached (FREE_QUOTA_EXCEEDED; body carries keep_going_url and a question_pack payment link); the subscription is paused or its card was declined (BILLING_INACTIVE; body links the one step that restores it, never an upgrade); or the tool refused for credits (INSUFFICIENT_CREDITS, PAYMENT_REQUIRED; body carries the tool result); or the tool hit a plan limit (the code is the refusal code itself: PROMPT_LIMIT, CADENCE_LIMIT, MONITOR_LIMIT, PAGE_LIMIT_EXCEEDED, SEAT_LIMIT_EXCEEDED, WORKSPACE_LIMIT_EXCEEDED, PLANNER_DISABLED, AUTO_EXECUTE_DISABLED, AGENT_SKILLS_NOT_ENTITLED, PAGE_TEMPLATES_NOT_ENTITLED, HOSTED_PAGES_NOT_ENTITLED, AI_ATTRIBUTION_NOT_ENTITLED, ZAPIER_NOT_ENTITLED, BYO_KEYS_NOT_ENTITLED, INCREMENTALITY_NOT_ENTITLED, WEBHOOKS_NOT_ENTITLED; `result` holds the tool refusal). Body carries upgrade_url (and reason, for tool refusals) where an upgrade is the fix. |
403 | The plan allows it but the key creator's role in the workspace does not (FORBIDDEN_ROLE; e.g. a creator now a viewer calling an acting tool). No upgrade fixes it: an admin changes the role. |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
409 | A request with this Idempotency-Key is still running (IDEMPOTENCY_IN_PROGRESS; repeat after Retry-After to collect the result), or it ran and its answer was too large to keep (IDEMPOTENCY_RESULT_NOT_KEPT; it is not run again). |
413 | Request body over 256 KB (BODY_TOO_LARGE). Tool arguments are small JSON objects. |
422 | The tool refused: it needs a confirmation step first (NEEDS_CONFIRMATION), or it declined for another reason it states (TOOL_REFUSED); result holds its explanation. Or this Idempotency-Key was used for a different tool or arguments (IDEMPOTENCY_KEY_REUSED). |
429 | Rate limited: the per-key tool-call limit (Retry-After header set), or the tool refused for a rate cap (e.g. ARTICLE_FAILURE_CAP; body carries the tool result). |
502 | Tool execution failed (TOOL_FAILED) |
503 | Temporarily unavailable, on our side, not a limit: the upstream data provider or the credit check is down (PROVIDER_UNAVAILABLE; nothing was charged), or idempotency is unavailable and the tool was NOT run (IDEMPOTENCY_UNAVAILABLE). Retry shortly. |
504 | The tool is still running past the 60s response ceiling and was not stopped (TOOL_TIMEOUT). With an Idempotency-Key, repeat the request to collect its answer. |
curl -X POST "https://app.seomatic.ai/api/v1/tools/run_ai_visibility_scan" \
-H "Authorization: Bearer $SEOMATIC_API_KEY" \
-H "Idempotency-Key: $(uuidgen)"/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, current cadence, and every AI engi…
| 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 answered. result is its output, usually a JSON string (parse it). A tool that refuses does NOT answer 200: it gets the matching 402/422/429/503 below, with its own output in result. |
400 | Invalid arguments (INVALID_ARGUMENTS; details says what) or a malformed Idempotency-Key (INVALID_IDEMPOTENCY_KEY). |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA); the plan does not include acting through the API (SCOPE_REVOKED_BY_PLAN); X-Seomatic-Client is n8n or make and the workspace has no paid plan or trial (AUTOMATION_NOT_ENTITLED); the free monthly question limit is reached (FREE_QUOTA_EXCEEDED; body carries keep_going_url and a question_pack payment link); the subscription is paused or its card was declined (BILLING_INACTIVE; body links the one step that restores it, never an upgrade); or the tool refused for credits (INSUFFICIENT_CREDITS, PAYMENT_REQUIRED; body carries the tool result); or the tool hit a plan limit (the code is the refusal code itself: PROMPT_LIMIT, CADENCE_LIMIT, MONITOR_LIMIT, PAGE_LIMIT_EXCEEDED, SEAT_LIMIT_EXCEEDED, WORKSPACE_LIMIT_EXCEEDED, PLANNER_DISABLED, AUTO_EXECUTE_DISABLED, AGENT_SKILLS_NOT_ENTITLED, PAGE_TEMPLATES_NOT_ENTITLED, HOSTED_PAGES_NOT_ENTITLED, AI_ATTRIBUTION_NOT_ENTITLED, ZAPIER_NOT_ENTITLED, BYO_KEYS_NOT_ENTITLED, INCREMENTALITY_NOT_ENTITLED, WEBHOOKS_NOT_ENTITLED; `result` holds the tool refusal). Body carries upgrade_url (and reason, for tool refusals) where an upgrade is the fix. |
403 | The plan allows it but the key creator's role in the workspace does not (FORBIDDEN_ROLE; e.g. a creator now a viewer calling an acting tool). No upgrade fixes it: an admin changes the role. |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
409 | A request with this Idempotency-Key is still running (IDEMPOTENCY_IN_PROGRESS; repeat after Retry-After to collect the result), or it ran and its answer was too large to keep (IDEMPOTENCY_RESULT_NOT_KEPT; it is not run again). |
413 | Request body over 256 KB (BODY_TOO_LARGE). Tool arguments are small JSON objects. |
422 | The tool refused: it needs a confirmation step first (NEEDS_CONFIRMATION), or it declined for another reason it states (TOOL_REFUSED); result holds its explanation. Or this Idempotency-Key was used for a different tool or arguments (IDEMPOTENCY_KEY_REUSED). |
429 | Rate limited: the per-key tool-call limit (Retry-After header set), or the tool refused for a rate cap (e.g. ARTICLE_FAILURE_CAP; body carries the tool result). |
502 | Tool execution failed (TOOL_FAILED) |
503 | Temporarily unavailable, on our side, not a limit: the upstream data provider or the credit check is down (PROVIDER_UNAVAILABLE; nothing was charged), or idempotency is unavailable and the tool was NOT run (IDEMPOTENCY_UNAVAILABLE). Retry shortly. |
504 | The tool is still running past the 60s response ceiling and was not stopped (TOOL_TIMEOUT). With an Idempotency-Key, repeat the request to collect its answer. |
curl -X POST "https://app.seomatic.ai/api/v1/tools/list_tracked_prompts" \
-H "Authorization: Bearer $SEOMATIC_API_KEY" \
-H "Idempotency-Key: $(uuidgen)"/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 answered. result is its output, usually a JSON string (parse it). A tool that refuses does NOT answer 200: it gets the matching 402/422/429/503 below, with its own output in result. |
400 | Invalid arguments (INVALID_ARGUMENTS; details says what) or a malformed Idempotency-Key (INVALID_IDEMPOTENCY_KEY). |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA); the plan does not include acting through the API (SCOPE_REVOKED_BY_PLAN); X-Seomatic-Client is n8n or make and the workspace has no paid plan or trial (AUTOMATION_NOT_ENTITLED); the free monthly question limit is reached (FREE_QUOTA_EXCEEDED; body carries keep_going_url and a question_pack payment link); the subscription is paused or its card was declined (BILLING_INACTIVE; body links the one step that restores it, never an upgrade); or the tool refused for credits (INSUFFICIENT_CREDITS, PAYMENT_REQUIRED; body carries the tool result); or the tool hit a plan limit (the code is the refusal code itself: PROMPT_LIMIT, CADENCE_LIMIT, MONITOR_LIMIT, PAGE_LIMIT_EXCEEDED, SEAT_LIMIT_EXCEEDED, WORKSPACE_LIMIT_EXCEEDED, PLANNER_DISABLED, AUTO_EXECUTE_DISABLED, AGENT_SKILLS_NOT_ENTITLED, PAGE_TEMPLATES_NOT_ENTITLED, HOSTED_PAGES_NOT_ENTITLED, AI_ATTRIBUTION_NOT_ENTITLED, ZAPIER_NOT_ENTITLED, BYO_KEYS_NOT_ENTITLED, INCREMENTALITY_NOT_ENTITLED, WEBHOOKS_NOT_ENTITLED; `result` holds the tool refusal). Body carries upgrade_url (and reason, for tool refusals) where an upgrade is the fix. |
403 | The plan allows it but the key creator's role in the workspace does not (FORBIDDEN_ROLE; e.g. a creator now a viewer calling an acting tool). No upgrade fixes it: an admin changes the role. |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
409 | A request with this Idempotency-Key is still running (IDEMPOTENCY_IN_PROGRESS; repeat after Retry-After to collect the result), or it ran and its answer was too large to keep (IDEMPOTENCY_RESULT_NOT_KEPT; it is not run again). |
413 | Request body over 256 KB (BODY_TOO_LARGE). Tool arguments are small JSON objects. |
422 | The tool refused: it needs a confirmation step first (NEEDS_CONFIRMATION), or it declined for another reason it states (TOOL_REFUSED); result holds its explanation. Or this Idempotency-Key was used for a different tool or arguments (IDEMPOTENCY_KEY_REUSED). |
429 | Rate limited: the per-key tool-call limit (Retry-After header set), or the tool refused for a rate cap (e.g. ARTICLE_FAILURE_CAP; body carries the tool result). |
502 | Tool execution failed (TOOL_FAILED) |
503 | Temporarily unavailable, on our side, not a limit: the upstream data provider or the credit check is down (PROVIDER_UNAVAILABLE; nothing was charged), or idempotency is unavailable and the tool was NOT run (IDEMPOTENCY_UNAVAILABLE). Retry shortly. |
504 | The tool is still running past the 60s response ceiling and was not stopped (TOOL_TIMEOUT). With an Idempotency-Key, repeat the request to collect its answer. |
curl -X POST "https://app.seomatic.ai/api/v1/tools/add_tracked_prompt" \
-H "Authorization: Bearer $SEOMATIC_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"prompt":"…"}'/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 answered. result is its output, usually a JSON string (parse it). A tool that refuses does NOT answer 200: it gets the matching 402/422/429/503 below, with its own output in result. |
400 | Invalid arguments (INVALID_ARGUMENTS; details says what) or a malformed Idempotency-Key (INVALID_IDEMPOTENCY_KEY). |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA); the plan does not include acting through the API (SCOPE_REVOKED_BY_PLAN); X-Seomatic-Client is n8n or make and the workspace has no paid plan or trial (AUTOMATION_NOT_ENTITLED); the free monthly question limit is reached (FREE_QUOTA_EXCEEDED; body carries keep_going_url and a question_pack payment link); the subscription is paused or its card was declined (BILLING_INACTIVE; body links the one step that restores it, never an upgrade); or the tool refused for credits (INSUFFICIENT_CREDITS, PAYMENT_REQUIRED; body carries the tool result); or the tool hit a plan limit (the code is the refusal code itself: PROMPT_LIMIT, CADENCE_LIMIT, MONITOR_LIMIT, PAGE_LIMIT_EXCEEDED, SEAT_LIMIT_EXCEEDED, WORKSPACE_LIMIT_EXCEEDED, PLANNER_DISABLED, AUTO_EXECUTE_DISABLED, AGENT_SKILLS_NOT_ENTITLED, PAGE_TEMPLATES_NOT_ENTITLED, HOSTED_PAGES_NOT_ENTITLED, AI_ATTRIBUTION_NOT_ENTITLED, ZAPIER_NOT_ENTITLED, BYO_KEYS_NOT_ENTITLED, INCREMENTALITY_NOT_ENTITLED, WEBHOOKS_NOT_ENTITLED; `result` holds the tool refusal). Body carries upgrade_url (and reason, for tool refusals) where an upgrade is the fix. |
403 | The plan allows it but the key creator's role in the workspace does not (FORBIDDEN_ROLE; e.g. a creator now a viewer calling an acting tool). No upgrade fixes it: an admin changes the role. |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
409 | A request with this Idempotency-Key is still running (IDEMPOTENCY_IN_PROGRESS; repeat after Retry-After to collect the result), or it ran and its answer was too large to keep (IDEMPOTENCY_RESULT_NOT_KEPT; it is not run again). |
413 | Request body over 256 KB (BODY_TOO_LARGE). Tool arguments are small JSON objects. |
422 | The tool refused: it needs a confirmation step first (NEEDS_CONFIRMATION), or it declined for another reason it states (TOOL_REFUSED); result holds its explanation. Or this Idempotency-Key was used for a different tool or arguments (IDEMPOTENCY_KEY_REUSED). |
429 | Rate limited: the per-key tool-call limit (Retry-After header set), or the tool refused for a rate cap (e.g. ARTICLE_FAILURE_CAP; body carries the tool result). |
502 | Tool execution failed (TOOL_FAILED) |
503 | Temporarily unavailable, on our side, not a limit: the upstream data provider or the credit check is down (PROVIDER_UNAVAILABLE; nothing was charged), or idempotency is unavailable and the tool was NOT run (IDEMPOTENCY_UNAVAILABLE). Retry shortly. |
504 | The tool is still running past the 60s response ceiling and was not stopped (TOOL_TIMEOUT). With an Idempotency-Key, repeat the request to collect its answer. |
curl -X POST "https://app.seomatic.ai/api/v1/tools/update_tracked_prompt" \
-H "Authorization: Bearer $SEOMATIC_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"promptId":"00000000-0000-0000-0000-000000000000"}'/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 answered. result is its output, usually a JSON string (parse it). A tool that refuses does NOT answer 200: it gets the matching 402/422/429/503 below, with its own output in result. |
400 | Invalid arguments (INVALID_ARGUMENTS; details says what) or a malformed Idempotency-Key (INVALID_IDEMPOTENCY_KEY). |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA); the plan does not include acting through the API (SCOPE_REVOKED_BY_PLAN); X-Seomatic-Client is n8n or make and the workspace has no paid plan or trial (AUTOMATION_NOT_ENTITLED); the free monthly question limit is reached (FREE_QUOTA_EXCEEDED; body carries keep_going_url and a question_pack payment link); the subscription is paused or its card was declined (BILLING_INACTIVE; body links the one step that restores it, never an upgrade); or the tool refused for credits (INSUFFICIENT_CREDITS, PAYMENT_REQUIRED; body carries the tool result); or the tool hit a plan limit (the code is the refusal code itself: PROMPT_LIMIT, CADENCE_LIMIT, MONITOR_LIMIT, PAGE_LIMIT_EXCEEDED, SEAT_LIMIT_EXCEEDED, WORKSPACE_LIMIT_EXCEEDED, PLANNER_DISABLED, AUTO_EXECUTE_DISABLED, AGENT_SKILLS_NOT_ENTITLED, PAGE_TEMPLATES_NOT_ENTITLED, HOSTED_PAGES_NOT_ENTITLED, AI_ATTRIBUTION_NOT_ENTITLED, ZAPIER_NOT_ENTITLED, BYO_KEYS_NOT_ENTITLED, INCREMENTALITY_NOT_ENTITLED, WEBHOOKS_NOT_ENTITLED; `result` holds the tool refusal). Body carries upgrade_url (and reason, for tool refusals) where an upgrade is the fix. |
403 | The plan allows it but the key creator's role in the workspace does not (FORBIDDEN_ROLE; e.g. a creator now a viewer calling an acting tool). No upgrade fixes it: an admin changes the role. |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
409 | A request with this Idempotency-Key is still running (IDEMPOTENCY_IN_PROGRESS; repeat after Retry-After to collect the result), or it ran and its answer was too large to keep (IDEMPOTENCY_RESULT_NOT_KEPT; it is not run again). |
413 | Request body over 256 KB (BODY_TOO_LARGE). Tool arguments are small JSON objects. |
422 | The tool refused: it needs a confirmation step first (NEEDS_CONFIRMATION), or it declined for another reason it states (TOOL_REFUSED); result holds its explanation. Or this Idempotency-Key was used for a different tool or arguments (IDEMPOTENCY_KEY_REUSED). |
429 | Rate limited: the per-key tool-call limit (Retry-After header set), or the tool refused for a rate cap (e.g. ARTICLE_FAILURE_CAP; body carries the tool result). |
502 | Tool execution failed (TOOL_FAILED) |
503 | Temporarily unavailable, on our side, not a limit: the upstream data provider or the credit check is down (PROVIDER_UNAVAILABLE; nothing was charged), or idempotency is unavailable and the tool was NOT run (IDEMPOTENCY_UNAVAILABLE). Retry shortly. |
504 | The tool is still running past the 60s response ceiling and was not stopped (TOOL_TIMEOUT). With an Idempotency-Key, repeat the request to collect its answer. |
curl -X POST "https://app.seomatic.ai/api/v1/tools/remove_tracked_prompt" \
-H "Authorization: Bearer $SEOMATIC_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-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 answered. result is its output, usually a JSON string (parse it). A tool that refuses does NOT answer 200: it gets the matching 402/422/429/503 below, with its own output in result. |
400 | Invalid arguments (INVALID_ARGUMENTS; details says what) or a malformed Idempotency-Key (INVALID_IDEMPOTENCY_KEY). |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA); the plan does not include acting through the API (SCOPE_REVOKED_BY_PLAN); X-Seomatic-Client is n8n or make and the workspace has no paid plan or trial (AUTOMATION_NOT_ENTITLED); the free monthly question limit is reached (FREE_QUOTA_EXCEEDED; body carries keep_going_url and a question_pack payment link); the subscription is paused or its card was declined (BILLING_INACTIVE; body links the one step that restores it, never an upgrade); or the tool refused for credits (INSUFFICIENT_CREDITS, PAYMENT_REQUIRED; body carries the tool result); or the tool hit a plan limit (the code is the refusal code itself: PROMPT_LIMIT, CADENCE_LIMIT, MONITOR_LIMIT, PAGE_LIMIT_EXCEEDED, SEAT_LIMIT_EXCEEDED, WORKSPACE_LIMIT_EXCEEDED, PLANNER_DISABLED, AUTO_EXECUTE_DISABLED, AGENT_SKILLS_NOT_ENTITLED, PAGE_TEMPLATES_NOT_ENTITLED, HOSTED_PAGES_NOT_ENTITLED, AI_ATTRIBUTION_NOT_ENTITLED, ZAPIER_NOT_ENTITLED, BYO_KEYS_NOT_ENTITLED, INCREMENTALITY_NOT_ENTITLED, WEBHOOKS_NOT_ENTITLED; `result` holds the tool refusal). Body carries upgrade_url (and reason, for tool refusals) where an upgrade is the fix. |
403 | The plan allows it but the key creator's role in the workspace does not (FORBIDDEN_ROLE; e.g. a creator now a viewer calling an acting tool). No upgrade fixes it: an admin changes the role. |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
409 | A request with this Idempotency-Key is still running (IDEMPOTENCY_IN_PROGRESS; repeat after Retry-After to collect the result), or it ran and its answer was too large to keep (IDEMPOTENCY_RESULT_NOT_KEPT; it is not run again). |
413 | Request body over 256 KB (BODY_TOO_LARGE). Tool arguments are small JSON objects. |
422 | The tool refused: it needs a confirmation step first (NEEDS_CONFIRMATION), or it declined for another reason it states (TOOL_REFUSED); result holds its explanation. Or this Idempotency-Key was used for a different tool or arguments (IDEMPOTENCY_KEY_REUSED). |
429 | Rate limited: the per-key tool-call limit (Retry-After header set), or the tool refused for a rate cap (e.g. ARTICLE_FAILURE_CAP; body carries the tool result). |
502 | Tool execution failed (TOOL_FAILED) |
503 | Temporarily unavailable, on our side, not a limit: the upstream data provider or the credit check is down (PROVIDER_UNAVAILABLE; nothing was charged), or idempotency is unavailable and the tool was NOT run (IDEMPOTENCY_UNAVAILABLE). Retry shortly. |
504 | The tool is still running past the 60s response ceiling and was not stopped (TOOL_TIMEOUT). With an Idempotency-Key, repeat the request to collect its answer. |
curl -X POST "https://app.seomatic.ai/api/v1/tools/set_scan_cadence" \
-H "Authorization: Bearer $SEOMATIC_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"cadence":"weekly"}'/tools/set_monitor_enginesactsChoose which AI engines AI-visibility scans query. Options: openai, anthropic, google-aio, perplexity, google-ai-mode, copilot, gemini, grok; defaults: openai, anthropic, google-aio. Pass the full li…
| Name | Type | Required | Description |
|---|---|---|---|
engines | string[] | no | The complete set of engines to track |
reset | boolean | no | true = track the default engines |
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 answered. result is its output, usually a JSON string (parse it). A tool that refuses does NOT answer 200: it gets the matching 402/422/429/503 below, with its own output in result. |
400 | Invalid arguments (INVALID_ARGUMENTS; details says what) or a malformed Idempotency-Key (INVALID_IDEMPOTENCY_KEY). |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA); the plan does not include acting through the API (SCOPE_REVOKED_BY_PLAN); X-Seomatic-Client is n8n or make and the workspace has no paid plan or trial (AUTOMATION_NOT_ENTITLED); the free monthly question limit is reached (FREE_QUOTA_EXCEEDED; body carries keep_going_url and a question_pack payment link); the subscription is paused or its card was declined (BILLING_INACTIVE; body links the one step that restores it, never an upgrade); or the tool refused for credits (INSUFFICIENT_CREDITS, PAYMENT_REQUIRED; body carries the tool result); or the tool hit a plan limit (the code is the refusal code itself: PROMPT_LIMIT, CADENCE_LIMIT, MONITOR_LIMIT, PAGE_LIMIT_EXCEEDED, SEAT_LIMIT_EXCEEDED, WORKSPACE_LIMIT_EXCEEDED, PLANNER_DISABLED, AUTO_EXECUTE_DISABLED, AGENT_SKILLS_NOT_ENTITLED, PAGE_TEMPLATES_NOT_ENTITLED, HOSTED_PAGES_NOT_ENTITLED, AI_ATTRIBUTION_NOT_ENTITLED, ZAPIER_NOT_ENTITLED, BYO_KEYS_NOT_ENTITLED, INCREMENTALITY_NOT_ENTITLED, WEBHOOKS_NOT_ENTITLED; `result` holds the tool refusal). Body carries upgrade_url (and reason, for tool refusals) where an upgrade is the fix. |
403 | The plan allows it but the key creator's role in the workspace does not (FORBIDDEN_ROLE; e.g. a creator now a viewer calling an acting tool). No upgrade fixes it: an admin changes the role. |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
409 | A request with this Idempotency-Key is still running (IDEMPOTENCY_IN_PROGRESS; repeat after Retry-After to collect the result), or it ran and its answer was too large to keep (IDEMPOTENCY_RESULT_NOT_KEPT; it is not run again). |
413 | Request body over 256 KB (BODY_TOO_LARGE). Tool arguments are small JSON objects. |
422 | The tool refused: it needs a confirmation step first (NEEDS_CONFIRMATION), or it declined for another reason it states (TOOL_REFUSED); result holds its explanation. Or this Idempotency-Key was used for a different tool or arguments (IDEMPOTENCY_KEY_REUSED). |
429 | Rate limited: the per-key tool-call limit (Retry-After header set), or the tool refused for a rate cap (e.g. ARTICLE_FAILURE_CAP; body carries the tool result). |
502 | Tool execution failed (TOOL_FAILED) |
503 | Temporarily unavailable, on our side, not a limit: the upstream data provider or the credit check is down (PROVIDER_UNAVAILABLE; nothing was charged), or idempotency is unavailable and the tool was NOT run (IDEMPOTENCY_UNAVAILABLE). Retry shortly. |
504 | The tool is still running past the 60s response ceiling and was not stopped (TOOL_TIMEOUT). With an Idempotency-Key, repeat the request to collect its answer. |
curl -X POST "https://app.seomatic.ai/api/v1/tools/set_monitor_engines" \
-H "Authorization: Bearer $SEOMATIC_API_KEY" \
-H "Idempotency-Key: $(uuidgen)"/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 answered. result is its output, usually a JSON string (parse it). A tool that refuses does NOT answer 200: it gets the matching 402/422/429/503 below, with its own output in result. |
400 | Invalid arguments (INVALID_ARGUMENTS; details says what) or a malformed Idempotency-Key (INVALID_IDEMPOTENCY_KEY). |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA); the plan does not include acting through the API (SCOPE_REVOKED_BY_PLAN); X-Seomatic-Client is n8n or make and the workspace has no paid plan or trial (AUTOMATION_NOT_ENTITLED); the free monthly question limit is reached (FREE_QUOTA_EXCEEDED; body carries keep_going_url and a question_pack payment link); the subscription is paused or its card was declined (BILLING_INACTIVE; body links the one step that restores it, never an upgrade); or the tool refused for credits (INSUFFICIENT_CREDITS, PAYMENT_REQUIRED; body carries the tool result); or the tool hit a plan limit (the code is the refusal code itself: PROMPT_LIMIT, CADENCE_LIMIT, MONITOR_LIMIT, PAGE_LIMIT_EXCEEDED, SEAT_LIMIT_EXCEEDED, WORKSPACE_LIMIT_EXCEEDED, PLANNER_DISABLED, AUTO_EXECUTE_DISABLED, AGENT_SKILLS_NOT_ENTITLED, PAGE_TEMPLATES_NOT_ENTITLED, HOSTED_PAGES_NOT_ENTITLED, AI_ATTRIBUTION_NOT_ENTITLED, ZAPIER_NOT_ENTITLED, BYO_KEYS_NOT_ENTITLED, INCREMENTALITY_NOT_ENTITLED, WEBHOOKS_NOT_ENTITLED; `result` holds the tool refusal). Body carries upgrade_url (and reason, for tool refusals) where an upgrade is the fix. |
403 | The plan allows it but the key creator's role in the workspace does not (FORBIDDEN_ROLE; e.g. a creator now a viewer calling an acting tool). No upgrade fixes it: an admin changes the role. |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
409 | A request with this Idempotency-Key is still running (IDEMPOTENCY_IN_PROGRESS; repeat after Retry-After to collect the result), or it ran and its answer was too large to keep (IDEMPOTENCY_RESULT_NOT_KEPT; it is not run again). |
413 | Request body over 256 KB (BODY_TOO_LARGE). Tool arguments are small JSON objects. |
422 | The tool refused: it needs a confirmation step first (NEEDS_CONFIRMATION), or it declined for another reason it states (TOOL_REFUSED); result holds its explanation. Or this Idempotency-Key was used for a different tool or arguments (IDEMPOTENCY_KEY_REUSED). |
429 | Rate limited: the per-key tool-call limit (Retry-After header set), or the tool refused for a rate cap (e.g. ARTICLE_FAILURE_CAP; body carries the tool result). |
502 | Tool execution failed (TOOL_FAILED) |
503 | Temporarily unavailable, on our side, not a limit: the upstream data provider or the credit check is down (PROVIDER_UNAVAILABLE; nothing was charged), or idempotency is unavailable and the tool was NOT run (IDEMPOTENCY_UNAVAILABLE). Retry shortly. |
504 | The tool is still running past the 60s response ceiling and was not stopped (TOOL_TIMEOUT). With an Idempotency-Key, repeat the request to collect its answer. |
curl -X POST "https://app.seomatic.ai/api/v1/tools/get_ai_crawler_activity" \
-H "Authorization: Bearer $SEOMATIC_API_KEY"/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 answered. result is its output, usually a JSON string (parse it). A tool that refuses does NOT answer 200: it gets the matching 402/422/429/503 below, with its own output in result. |
400 | Invalid arguments (INVALID_ARGUMENTS; details says what) or a malformed Idempotency-Key (INVALID_IDEMPOTENCY_KEY). |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA); the plan does not include acting through the API (SCOPE_REVOKED_BY_PLAN); X-Seomatic-Client is n8n or make and the workspace has no paid plan or trial (AUTOMATION_NOT_ENTITLED); the free monthly question limit is reached (FREE_QUOTA_EXCEEDED; body carries keep_going_url and a question_pack payment link); the subscription is paused or its card was declined (BILLING_INACTIVE; body links the one step that restores it, never an upgrade); or the tool refused for credits (INSUFFICIENT_CREDITS, PAYMENT_REQUIRED; body carries the tool result); or the tool hit a plan limit (the code is the refusal code itself: PROMPT_LIMIT, CADENCE_LIMIT, MONITOR_LIMIT, PAGE_LIMIT_EXCEEDED, SEAT_LIMIT_EXCEEDED, WORKSPACE_LIMIT_EXCEEDED, PLANNER_DISABLED, AUTO_EXECUTE_DISABLED, AGENT_SKILLS_NOT_ENTITLED, PAGE_TEMPLATES_NOT_ENTITLED, HOSTED_PAGES_NOT_ENTITLED, AI_ATTRIBUTION_NOT_ENTITLED, ZAPIER_NOT_ENTITLED, BYO_KEYS_NOT_ENTITLED, INCREMENTALITY_NOT_ENTITLED, WEBHOOKS_NOT_ENTITLED; `result` holds the tool refusal). Body carries upgrade_url (and reason, for tool refusals) where an upgrade is the fix. |
403 | The plan allows it but the key creator's role in the workspace does not (FORBIDDEN_ROLE; e.g. a creator now a viewer calling an acting tool). No upgrade fixes it: an admin changes the role. |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
409 | A request with this Idempotency-Key is still running (IDEMPOTENCY_IN_PROGRESS; repeat after Retry-After to collect the result), or it ran and its answer was too large to keep (IDEMPOTENCY_RESULT_NOT_KEPT; it is not run again). |
413 | Request body over 256 KB (BODY_TOO_LARGE). Tool arguments are small JSON objects. |
422 | The tool refused: it needs a confirmation step first (NEEDS_CONFIRMATION), or it declined for another reason it states (TOOL_REFUSED); result holds its explanation. Or this Idempotency-Key was used for a different tool or arguments (IDEMPOTENCY_KEY_REUSED). |
429 | Rate limited: the per-key tool-call limit (Retry-After header set), or the tool refused for a rate cap (e.g. ARTICLE_FAILURE_CAP; body carries the tool result). |
502 | Tool execution failed (TOOL_FAILED) |
503 | Temporarily unavailable, on our side, not a limit: the upstream data provider or the credit check is down (PROVIDER_UNAVAILABLE; nothing was charged), or idempotency is unavailable and the tool was NOT run (IDEMPOTENCY_UNAVAILABLE). Retry shortly. |
504 | The tool is still running past the 60s response ceiling and was not stopped (TOOL_TIMEOUT). With an Idempotency-Key, repeat the request to collect its answer. |
curl -X POST "https://app.seomatic.ai/api/v1/tools/get_trust_entities" \
-H "Authorization: Bearer $SEOMATIC_API_KEY"/tools/get_trust_factsreadThe workspace's trust profile: the provenance-tracked, verifiable business facts (credentials, years of experience, awards, review counts, guarantees) the agent's writers are allowed to claim in E-E-…
| Status | Description |
|---|---|
200 | { tool, result }: the tool answered. result is its output, usually a JSON string (parse it). A tool that refuses does NOT answer 200: it gets the matching 402/422/429/503 below, with its own output in result. |
400 | Invalid arguments (INVALID_ARGUMENTS; details says what) or a malformed Idempotency-Key (INVALID_IDEMPOTENCY_KEY). |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA); the plan does not include acting through the API (SCOPE_REVOKED_BY_PLAN); X-Seomatic-Client is n8n or make and the workspace has no paid plan or trial (AUTOMATION_NOT_ENTITLED); the free monthly question limit is reached (FREE_QUOTA_EXCEEDED; body carries keep_going_url and a question_pack payment link); the subscription is paused or its card was declined (BILLING_INACTIVE; body links the one step that restores it, never an upgrade); or the tool refused for credits (INSUFFICIENT_CREDITS, PAYMENT_REQUIRED; body carries the tool result); or the tool hit a plan limit (the code is the refusal code itself: PROMPT_LIMIT, CADENCE_LIMIT, MONITOR_LIMIT, PAGE_LIMIT_EXCEEDED, SEAT_LIMIT_EXCEEDED, WORKSPACE_LIMIT_EXCEEDED, PLANNER_DISABLED, AUTO_EXECUTE_DISABLED, AGENT_SKILLS_NOT_ENTITLED, PAGE_TEMPLATES_NOT_ENTITLED, HOSTED_PAGES_NOT_ENTITLED, AI_ATTRIBUTION_NOT_ENTITLED, ZAPIER_NOT_ENTITLED, BYO_KEYS_NOT_ENTITLED, INCREMENTALITY_NOT_ENTITLED, WEBHOOKS_NOT_ENTITLED; `result` holds the tool refusal). Body carries upgrade_url (and reason, for tool refusals) where an upgrade is the fix. |
403 | The plan allows it but the key creator's role in the workspace does not (FORBIDDEN_ROLE; e.g. a creator now a viewer calling an acting tool). No upgrade fixes it: an admin changes the role. |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
409 | A request with this Idempotency-Key is still running (IDEMPOTENCY_IN_PROGRESS; repeat after Retry-After to collect the result), or it ran and its answer was too large to keep (IDEMPOTENCY_RESULT_NOT_KEPT; it is not run again). |
413 | Request body over 256 KB (BODY_TOO_LARGE). Tool arguments are small JSON objects. |
422 | The tool refused: it needs a confirmation step first (NEEDS_CONFIRMATION), or it declined for another reason it states (TOOL_REFUSED); result holds its explanation. Or this Idempotency-Key was used for a different tool or arguments (IDEMPOTENCY_KEY_REUSED). |
429 | Rate limited: the per-key tool-call limit (Retry-After header set), or the tool refused for a rate cap (e.g. ARTICLE_FAILURE_CAP; body carries the tool result). |
502 | Tool execution failed (TOOL_FAILED) |
503 | Temporarily unavailable, on our side, not a limit: the upstream data provider or the credit check is down (PROVIDER_UNAVAILABLE; nothing was charged), or idempotency is unavailable and the tool was NOT run (IDEMPOTENCY_UNAVAILABLE). Retry shortly. |
504 | The tool is still running past the 60s response ceiling and was not stopped (TOOL_TIMEOUT). With an Idempotency-Key, repeat the request to collect its answer. |
curl -X POST "https://app.seomatic.ai/api/v1/tools/get_trust_facts" \
-H "Authorization: Bearer $SEOMATIC_API_KEY"/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 answered. result is its output, usually a JSON string (parse it). A tool that refuses does NOT answer 200: it gets the matching 402/422/429/503 below, with its own output in result. |
400 | Invalid arguments (INVALID_ARGUMENTS; details says what) or a malformed Idempotency-Key (INVALID_IDEMPOTENCY_KEY). |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA); the plan does not include acting through the API (SCOPE_REVOKED_BY_PLAN); X-Seomatic-Client is n8n or make and the workspace has no paid plan or trial (AUTOMATION_NOT_ENTITLED); the free monthly question limit is reached (FREE_QUOTA_EXCEEDED; body carries keep_going_url and a question_pack payment link); the subscription is paused or its card was declined (BILLING_INACTIVE; body links the one step that restores it, never an upgrade); or the tool refused for credits (INSUFFICIENT_CREDITS, PAYMENT_REQUIRED; body carries the tool result); or the tool hit a plan limit (the code is the refusal code itself: PROMPT_LIMIT, CADENCE_LIMIT, MONITOR_LIMIT, PAGE_LIMIT_EXCEEDED, SEAT_LIMIT_EXCEEDED, WORKSPACE_LIMIT_EXCEEDED, PLANNER_DISABLED, AUTO_EXECUTE_DISABLED, AGENT_SKILLS_NOT_ENTITLED, PAGE_TEMPLATES_NOT_ENTITLED, HOSTED_PAGES_NOT_ENTITLED, AI_ATTRIBUTION_NOT_ENTITLED, ZAPIER_NOT_ENTITLED, BYO_KEYS_NOT_ENTITLED, INCREMENTALITY_NOT_ENTITLED, WEBHOOKS_NOT_ENTITLED; `result` holds the tool refusal). Body carries upgrade_url (and reason, for tool refusals) where an upgrade is the fix. |
403 | The plan allows it but the key creator's role in the workspace does not (FORBIDDEN_ROLE; e.g. a creator now a viewer calling an acting tool). No upgrade fixes it: an admin changes the role. |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
409 | A request with this Idempotency-Key is still running (IDEMPOTENCY_IN_PROGRESS; repeat after Retry-After to collect the result), or it ran and its answer was too large to keep (IDEMPOTENCY_RESULT_NOT_KEPT; it is not run again). |
413 | Request body over 256 KB (BODY_TOO_LARGE). Tool arguments are small JSON objects. |
422 | The tool refused: it needs a confirmation step first (NEEDS_CONFIRMATION), or it declined for another reason it states (TOOL_REFUSED); result holds its explanation. Or this Idempotency-Key was used for a different tool or arguments (IDEMPOTENCY_KEY_REUSED). |
429 | Rate limited: the per-key tool-call limit (Retry-After header set), or the tool refused for a rate cap (e.g. ARTICLE_FAILURE_CAP; body carries the tool result). |
502 | Tool execution failed (TOOL_FAILED) |
503 | Temporarily unavailable, on our side, not a limit: the upstream data provider or the credit check is down (PROVIDER_UNAVAILABLE; nothing was charged), or idempotency is unavailable and the tool was NOT run (IDEMPOTENCY_UNAVAILABLE). Retry shortly. |
504 | The tool is still running past the 60s response ceiling and was not stopped (TOOL_TIMEOUT). With an Idempotency-Key, repeat the request to collect its answer. |
curl -X POST "https://app.seomatic.ai/api/v1/tools/get_ai_funnel" \
-H "Authorization: Bearer $SEOMATIC_API_KEY"/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 answered. result is its output, usually a JSON string (parse it). A tool that refuses does NOT answer 200: it gets the matching 402/422/429/503 below, with its own output in result. |
400 | Invalid arguments (INVALID_ARGUMENTS; details says what) or a malformed Idempotency-Key (INVALID_IDEMPOTENCY_KEY). |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA); the plan does not include acting through the API (SCOPE_REVOKED_BY_PLAN); X-Seomatic-Client is n8n or make and the workspace has no paid plan or trial (AUTOMATION_NOT_ENTITLED); the free monthly question limit is reached (FREE_QUOTA_EXCEEDED; body carries keep_going_url and a question_pack payment link); the subscription is paused or its card was declined (BILLING_INACTIVE; body links the one step that restores it, never an upgrade); or the tool refused for credits (INSUFFICIENT_CREDITS, PAYMENT_REQUIRED; body carries the tool result); or the tool hit a plan limit (the code is the refusal code itself: PROMPT_LIMIT, CADENCE_LIMIT, MONITOR_LIMIT, PAGE_LIMIT_EXCEEDED, SEAT_LIMIT_EXCEEDED, WORKSPACE_LIMIT_EXCEEDED, PLANNER_DISABLED, AUTO_EXECUTE_DISABLED, AGENT_SKILLS_NOT_ENTITLED, PAGE_TEMPLATES_NOT_ENTITLED, HOSTED_PAGES_NOT_ENTITLED, AI_ATTRIBUTION_NOT_ENTITLED, ZAPIER_NOT_ENTITLED, BYO_KEYS_NOT_ENTITLED, INCREMENTALITY_NOT_ENTITLED, WEBHOOKS_NOT_ENTITLED; `result` holds the tool refusal). Body carries upgrade_url (and reason, for tool refusals) where an upgrade is the fix. |
403 | The plan allows it but the key creator's role in the workspace does not (FORBIDDEN_ROLE; e.g. a creator now a viewer calling an acting tool). No upgrade fixes it: an admin changes the role. |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
409 | A request with this Idempotency-Key is still running (IDEMPOTENCY_IN_PROGRESS; repeat after Retry-After to collect the result), or it ran and its answer was too large to keep (IDEMPOTENCY_RESULT_NOT_KEPT; it is not run again). |
413 | Request body over 256 KB (BODY_TOO_LARGE). Tool arguments are small JSON objects. |
422 | The tool refused: it needs a confirmation step first (NEEDS_CONFIRMATION), or it declined for another reason it states (TOOL_REFUSED); result holds its explanation. Or this Idempotency-Key was used for a different tool or arguments (IDEMPOTENCY_KEY_REUSED). |
429 | Rate limited: the per-key tool-call limit (Retry-After header set), or the tool refused for a rate cap (e.g. ARTICLE_FAILURE_CAP; body carries the tool result). |
502 | Tool execution failed (TOOL_FAILED) |
503 | Temporarily unavailable, on our side, not a limit: the upstream data provider or the credit check is down (PROVIDER_UNAVAILABLE; nothing was charged), or idempotency is unavailable and the tool was NOT run (IDEMPOTENCY_UNAVAILABLE). Retry shortly. |
504 | The tool is still running past the 60s response ceiling and was not stopped (TOOL_TIMEOUT). With an Idempotency-Key, repeat the request to collect its answer. |
curl -X POST "https://app.seomatic.ai/api/v1/tools/get_observed_citations" \
-H "Authorization: Bearer $SEOMATIC_API_KEY"/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 answered. result is its output, usually a JSON string (parse it). A tool that refuses does NOT answer 200: it gets the matching 402/422/429/503 below, with its own output in result. |
400 | Invalid arguments (INVALID_ARGUMENTS; details says what) or a malformed Idempotency-Key (INVALID_IDEMPOTENCY_KEY). |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA); the plan does not include acting through the API (SCOPE_REVOKED_BY_PLAN); X-Seomatic-Client is n8n or make and the workspace has no paid plan or trial (AUTOMATION_NOT_ENTITLED); the free monthly question limit is reached (FREE_QUOTA_EXCEEDED; body carries keep_going_url and a question_pack payment link); the subscription is paused or its card was declined (BILLING_INACTIVE; body links the one step that restores it, never an upgrade); or the tool refused for credits (INSUFFICIENT_CREDITS, PAYMENT_REQUIRED; body carries the tool result); or the tool hit a plan limit (the code is the refusal code itself: PROMPT_LIMIT, CADENCE_LIMIT, MONITOR_LIMIT, PAGE_LIMIT_EXCEEDED, SEAT_LIMIT_EXCEEDED, WORKSPACE_LIMIT_EXCEEDED, PLANNER_DISABLED, AUTO_EXECUTE_DISABLED, AGENT_SKILLS_NOT_ENTITLED, PAGE_TEMPLATES_NOT_ENTITLED, HOSTED_PAGES_NOT_ENTITLED, AI_ATTRIBUTION_NOT_ENTITLED, ZAPIER_NOT_ENTITLED, BYO_KEYS_NOT_ENTITLED, INCREMENTALITY_NOT_ENTITLED, WEBHOOKS_NOT_ENTITLED; `result` holds the tool refusal). Body carries upgrade_url (and reason, for tool refusals) where an upgrade is the fix. |
403 | The plan allows it but the key creator's role in the workspace does not (FORBIDDEN_ROLE; e.g. a creator now a viewer calling an acting tool). No upgrade fixes it: an admin changes the role. |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
409 | A request with this Idempotency-Key is still running (IDEMPOTENCY_IN_PROGRESS; repeat after Retry-After to collect the result), or it ran and its answer was too large to keep (IDEMPOTENCY_RESULT_NOT_KEPT; it is not run again). |
413 | Request body over 256 KB (BODY_TOO_LARGE). Tool arguments are small JSON objects. |
422 | The tool refused: it needs a confirmation step first (NEEDS_CONFIRMATION), or it declined for another reason it states (TOOL_REFUSED); result holds its explanation. Or this Idempotency-Key was used for a different tool or arguments (IDEMPOTENCY_KEY_REUSED). |
429 | Rate limited: the per-key tool-call limit (Retry-After header set), or the tool refused for a rate cap (e.g. ARTICLE_FAILURE_CAP; body carries the tool result). |
502 | Tool execution failed (TOOL_FAILED) |
503 | Temporarily unavailable, on our side, not a limit: the upstream data provider or the credit check is down (PROVIDER_UNAVAILABLE; nothing was charged), or idempotency is unavailable and the tool was NOT run (IDEMPOTENCY_UNAVAILABLE). Retry shortly. |
504 | The tool is still running past the 60s response ceiling and was not stopped (TOOL_TIMEOUT). With an Idempotency-Key, repeat the request to collect its answer. |
curl -X POST "https://app.seomatic.ai/api/v1/tools/get_page_ai_activity" \
-H "Authorization: Bearer $SEOMATIC_API_KEY"/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 answered. result is its output, usually a JSON string (parse it). A tool that refuses does NOT answer 200: it gets the matching 402/422/429/503 below, with its own output in result. |
400 | Invalid arguments (INVALID_ARGUMENTS; details says what) or a malformed Idempotency-Key (INVALID_IDEMPOTENCY_KEY). |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA); the plan does not include acting through the API (SCOPE_REVOKED_BY_PLAN); X-Seomatic-Client is n8n or make and the workspace has no paid plan or trial (AUTOMATION_NOT_ENTITLED); the free monthly question limit is reached (FREE_QUOTA_EXCEEDED; body carries keep_going_url and a question_pack payment link); the subscription is paused or its card was declined (BILLING_INACTIVE; body links the one step that restores it, never an upgrade); or the tool refused for credits (INSUFFICIENT_CREDITS, PAYMENT_REQUIRED; body carries the tool result); or the tool hit a plan limit (the code is the refusal code itself: PROMPT_LIMIT, CADENCE_LIMIT, MONITOR_LIMIT, PAGE_LIMIT_EXCEEDED, SEAT_LIMIT_EXCEEDED, WORKSPACE_LIMIT_EXCEEDED, PLANNER_DISABLED, AUTO_EXECUTE_DISABLED, AGENT_SKILLS_NOT_ENTITLED, PAGE_TEMPLATES_NOT_ENTITLED, HOSTED_PAGES_NOT_ENTITLED, AI_ATTRIBUTION_NOT_ENTITLED, ZAPIER_NOT_ENTITLED, BYO_KEYS_NOT_ENTITLED, INCREMENTALITY_NOT_ENTITLED, WEBHOOKS_NOT_ENTITLED; `result` holds the tool refusal). Body carries upgrade_url (and reason, for tool refusals) where an upgrade is the fix. |
403 | The plan allows it but the key creator's role in the workspace does not (FORBIDDEN_ROLE; e.g. a creator now a viewer calling an acting tool). No upgrade fixes it: an admin changes the role. |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
409 | A request with this Idempotency-Key is still running (IDEMPOTENCY_IN_PROGRESS; repeat after Retry-After to collect the result), or it ran and its answer was too large to keep (IDEMPOTENCY_RESULT_NOT_KEPT; it is not run again). |
413 | Request body over 256 KB (BODY_TOO_LARGE). Tool arguments are small JSON objects. |
422 | The tool refused: it needs a confirmation step first (NEEDS_CONFIRMATION), or it declined for another reason it states (TOOL_REFUSED); result holds its explanation. Or this Idempotency-Key was used for a different tool or arguments (IDEMPOTENCY_KEY_REUSED). |
429 | Rate limited: the per-key tool-call limit (Retry-After header set), or the tool refused for a rate cap (e.g. ARTICLE_FAILURE_CAP; body carries the tool result). |
502 | Tool execution failed (TOOL_FAILED) |
503 | Temporarily unavailable, on our side, not a limit: the upstream data provider or the credit check is down (PROVIDER_UNAVAILABLE; nothing was charged), or idempotency is unavailable and the tool was NOT run (IDEMPOTENCY_UNAVAILABLE). Retry shortly. |
504 | The tool is still running past the 60s response ceiling and was not stopped (TOOL_TIMEOUT). With an Idempotency-Key, repeat the request to collect its answer. |
curl -X POST "https://app.seomatic.ai/api/v1/tools/get_brand_facts" \
-H "Authorization: Bearer $SEOMATIC_API_KEY"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: the site's own market). Examples: 2840 US, 2826 UK, 2250 France, 2276 Germany. |
language_code | string | no | Language code (default: the site's own language). Examples: "en", "fr", "de". |
| Status | Description |
|---|---|
200 | { tool, result }: the tool answered. result is its output, usually a JSON string (parse it). A tool that refuses does NOT answer 200: it gets the matching 402/422/429/503 below, with its own output in result. |
400 | Invalid arguments (INVALID_ARGUMENTS; details says what) or a malformed Idempotency-Key (INVALID_IDEMPOTENCY_KEY). |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA); the plan does not include acting through the API (SCOPE_REVOKED_BY_PLAN); X-Seomatic-Client is n8n or make and the workspace has no paid plan or trial (AUTOMATION_NOT_ENTITLED); the free monthly question limit is reached (FREE_QUOTA_EXCEEDED; body carries keep_going_url and a question_pack payment link); the subscription is paused or its card was declined (BILLING_INACTIVE; body links the one step that restores it, never an upgrade); or the tool refused for credits (INSUFFICIENT_CREDITS, PAYMENT_REQUIRED; body carries the tool result); or the tool hit a plan limit (the code is the refusal code itself: PROMPT_LIMIT, CADENCE_LIMIT, MONITOR_LIMIT, PAGE_LIMIT_EXCEEDED, SEAT_LIMIT_EXCEEDED, WORKSPACE_LIMIT_EXCEEDED, PLANNER_DISABLED, AUTO_EXECUTE_DISABLED, AGENT_SKILLS_NOT_ENTITLED, PAGE_TEMPLATES_NOT_ENTITLED, HOSTED_PAGES_NOT_ENTITLED, AI_ATTRIBUTION_NOT_ENTITLED, ZAPIER_NOT_ENTITLED, BYO_KEYS_NOT_ENTITLED, INCREMENTALITY_NOT_ENTITLED, WEBHOOKS_NOT_ENTITLED; `result` holds the tool refusal). Body carries upgrade_url (and reason, for tool refusals) where an upgrade is the fix. |
403 | The plan allows it but the key creator's role in the workspace does not (FORBIDDEN_ROLE; e.g. a creator now a viewer calling an acting tool). No upgrade fixes it: an admin changes the role. |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
409 | A request with this Idempotency-Key is still running (IDEMPOTENCY_IN_PROGRESS; repeat after Retry-After to collect the result), or it ran and its answer was too large to keep (IDEMPOTENCY_RESULT_NOT_KEPT; it is not run again). |
413 | Request body over 256 KB (BODY_TOO_LARGE). Tool arguments are small JSON objects. |
422 | The tool refused: it needs a confirmation step first (NEEDS_CONFIRMATION), or it declined for another reason it states (TOOL_REFUSED); result holds its explanation. Or this Idempotency-Key was used for a different tool or arguments (IDEMPOTENCY_KEY_REUSED). |
429 | Rate limited: the per-key tool-call limit (Retry-After header set), or the tool refused for a rate cap (e.g. ARTICLE_FAILURE_CAP; body carries the tool result). |
502 | Tool execution failed (TOOL_FAILED) |
503 | Temporarily unavailable, on our side, not a limit: the upstream data provider or the credit check is down (PROVIDER_UNAVAILABLE; nothing was charged), or idempotency is unavailable and the tool was NOT run (IDEMPOTENCY_UNAVAILABLE). Retry shortly. |
504 | The tool is still running past the 60s response ceiling and was not stopped (TOOL_TIMEOUT). With an Idempotency-Key, repeat the request to collect its answer. |
curl -X POST "https://app.seomatic.ai/api/v1/tools/get_keyword_metrics" \
-H "Authorization: Bearer $SEOMATIC_API_KEY" \
-H "Content-Type: application/json" \
-d '{"keywords":[]}'/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: the site's own market). |
language_code | string | no | Language code (default: the site's own language). |
| Status | Description |
|---|---|
200 | { tool, result }: the tool answered. result is its output, usually a JSON string (parse it). A tool that refuses does NOT answer 200: it gets the matching 402/422/429/503 below, with its own output in result. |
400 | Invalid arguments (INVALID_ARGUMENTS; details says what) or a malformed Idempotency-Key (INVALID_IDEMPOTENCY_KEY). |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA); the plan does not include acting through the API (SCOPE_REVOKED_BY_PLAN); X-Seomatic-Client is n8n or make and the workspace has no paid plan or trial (AUTOMATION_NOT_ENTITLED); the free monthly question limit is reached (FREE_QUOTA_EXCEEDED; body carries keep_going_url and a question_pack payment link); the subscription is paused or its card was declined (BILLING_INACTIVE; body links the one step that restores it, never an upgrade); or the tool refused for credits (INSUFFICIENT_CREDITS, PAYMENT_REQUIRED; body carries the tool result); or the tool hit a plan limit (the code is the refusal code itself: PROMPT_LIMIT, CADENCE_LIMIT, MONITOR_LIMIT, PAGE_LIMIT_EXCEEDED, SEAT_LIMIT_EXCEEDED, WORKSPACE_LIMIT_EXCEEDED, PLANNER_DISABLED, AUTO_EXECUTE_DISABLED, AGENT_SKILLS_NOT_ENTITLED, PAGE_TEMPLATES_NOT_ENTITLED, HOSTED_PAGES_NOT_ENTITLED, AI_ATTRIBUTION_NOT_ENTITLED, ZAPIER_NOT_ENTITLED, BYO_KEYS_NOT_ENTITLED, INCREMENTALITY_NOT_ENTITLED, WEBHOOKS_NOT_ENTITLED; `result` holds the tool refusal). Body carries upgrade_url (and reason, for tool refusals) where an upgrade is the fix. |
403 | The plan allows it but the key creator's role in the workspace does not (FORBIDDEN_ROLE; e.g. a creator now a viewer calling an acting tool). No upgrade fixes it: an admin changes the role. |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
409 | A request with this Idempotency-Key is still running (IDEMPOTENCY_IN_PROGRESS; repeat after Retry-After to collect the result), or it ran and its answer was too large to keep (IDEMPOTENCY_RESULT_NOT_KEPT; it is not run again). |
413 | Request body over 256 KB (BODY_TOO_LARGE). Tool arguments are small JSON objects. |
422 | The tool refused: it needs a confirmation step first (NEEDS_CONFIRMATION), or it declined for another reason it states (TOOL_REFUSED); result holds its explanation. Or this Idempotency-Key was used for a different tool or arguments (IDEMPOTENCY_KEY_REUSED). |
429 | Rate limited: the per-key tool-call limit (Retry-After header set), or the tool refused for a rate cap (e.g. ARTICLE_FAILURE_CAP; body carries the tool result). |
502 | Tool execution failed (TOOL_FAILED) |
503 | Temporarily unavailable, on our side, not a limit: the upstream data provider or the credit check is down (PROVIDER_UNAVAILABLE; nothing was charged), or idempotency is unavailable and the tool was NOT run (IDEMPOTENCY_UNAVAILABLE). Retry shortly. |
504 | The tool is still running past the 60s response ceiling and was not stopped (TOOL_TIMEOUT). With an Idempotency-Key, repeat the request to collect its answer. |
curl -X POST "https://app.seomatic.ai/api/v1/tools/get_keyword_suggestions" \
-H "Authorization: Bearer $SEOMATIC_API_KEY" \
-H "Content-Type: application/json" \
-d '{"keywords":[]}'/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 answered. result is its output, usually a JSON string (parse it). A tool that refuses does NOT answer 200: it gets the matching 402/422/429/503 below, with its own output in result. |
400 | Invalid arguments (INVALID_ARGUMENTS; details says what) or a malformed Idempotency-Key (INVALID_IDEMPOTENCY_KEY). |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA); the plan does not include acting through the API (SCOPE_REVOKED_BY_PLAN); X-Seomatic-Client is n8n or make and the workspace has no paid plan or trial (AUTOMATION_NOT_ENTITLED); the free monthly question limit is reached (FREE_QUOTA_EXCEEDED; body carries keep_going_url and a question_pack payment link); the subscription is paused or its card was declined (BILLING_INACTIVE; body links the one step that restores it, never an upgrade); or the tool refused for credits (INSUFFICIENT_CREDITS, PAYMENT_REQUIRED; body carries the tool result); or the tool hit a plan limit (the code is the refusal code itself: PROMPT_LIMIT, CADENCE_LIMIT, MONITOR_LIMIT, PAGE_LIMIT_EXCEEDED, SEAT_LIMIT_EXCEEDED, WORKSPACE_LIMIT_EXCEEDED, PLANNER_DISABLED, AUTO_EXECUTE_DISABLED, AGENT_SKILLS_NOT_ENTITLED, PAGE_TEMPLATES_NOT_ENTITLED, HOSTED_PAGES_NOT_ENTITLED, AI_ATTRIBUTION_NOT_ENTITLED, ZAPIER_NOT_ENTITLED, BYO_KEYS_NOT_ENTITLED, INCREMENTALITY_NOT_ENTITLED, WEBHOOKS_NOT_ENTITLED; `result` holds the tool refusal). Body carries upgrade_url (and reason, for tool refusals) where an upgrade is the fix. |
403 | The plan allows it but the key creator's role in the workspace does not (FORBIDDEN_ROLE; e.g. a creator now a viewer calling an acting tool). No upgrade fixes it: an admin changes the role. |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
409 | A request with this Idempotency-Key is still running (IDEMPOTENCY_IN_PROGRESS; repeat after Retry-After to collect the result), or it ran and its answer was too large to keep (IDEMPOTENCY_RESULT_NOT_KEPT; it is not run again). |
413 | Request body over 256 KB (BODY_TOO_LARGE). Tool arguments are small JSON objects. |
422 | The tool refused: it needs a confirmation step first (NEEDS_CONFIRMATION), or it declined for another reason it states (TOOL_REFUSED); result holds its explanation. Or this Idempotency-Key was used for a different tool or arguments (IDEMPOTENCY_KEY_REUSED). |
429 | Rate limited: the per-key tool-call limit (Retry-After header set), or the tool refused for a rate cap (e.g. ARTICLE_FAILURE_CAP; body carries the tool result). |
502 | Tool execution failed (TOOL_FAILED) |
503 | Temporarily unavailable, on our side, not a limit: the upstream data provider or the credit check is down (PROVIDER_UNAVAILABLE; nothing was charged), or idempotency is unavailable and the tool was NOT run (IDEMPOTENCY_UNAVAILABLE). Retry shortly. |
504 | The tool is still running past the 60s response ceiling and was not stopped (TOOL_TIMEOUT). With an Idempotency-Key, repeat the request to collect its answer. |
curl -X POST "https://app.seomatic.ai/api/v1/tools/compare_keywords" \
-H "Authorization: Bearer $SEOMATIC_API_KEY" \
-H "Content-Type: application/json" \
-d '{"keywords":[]}'/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 answered. result is its output, usually a JSON string (parse it). A tool that refuses does NOT answer 200: it gets the matching 402/422/429/503 below, with its own output in result. |
400 | Invalid arguments (INVALID_ARGUMENTS; details says what) or a malformed Idempotency-Key (INVALID_IDEMPOTENCY_KEY). |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA); the plan does not include acting through the API (SCOPE_REVOKED_BY_PLAN); X-Seomatic-Client is n8n or make and the workspace has no paid plan or trial (AUTOMATION_NOT_ENTITLED); the free monthly question limit is reached (FREE_QUOTA_EXCEEDED; body carries keep_going_url and a question_pack payment link); the subscription is paused or its card was declined (BILLING_INACTIVE; body links the one step that restores it, never an upgrade); or the tool refused for credits (INSUFFICIENT_CREDITS, PAYMENT_REQUIRED; body carries the tool result); or the tool hit a plan limit (the code is the refusal code itself: PROMPT_LIMIT, CADENCE_LIMIT, MONITOR_LIMIT, PAGE_LIMIT_EXCEEDED, SEAT_LIMIT_EXCEEDED, WORKSPACE_LIMIT_EXCEEDED, PLANNER_DISABLED, AUTO_EXECUTE_DISABLED, AGENT_SKILLS_NOT_ENTITLED, PAGE_TEMPLATES_NOT_ENTITLED, HOSTED_PAGES_NOT_ENTITLED, AI_ATTRIBUTION_NOT_ENTITLED, ZAPIER_NOT_ENTITLED, BYO_KEYS_NOT_ENTITLED, INCREMENTALITY_NOT_ENTITLED, WEBHOOKS_NOT_ENTITLED; `result` holds the tool refusal). Body carries upgrade_url (and reason, for tool refusals) where an upgrade is the fix. |
403 | The plan allows it but the key creator's role in the workspace does not (FORBIDDEN_ROLE; e.g. a creator now a viewer calling an acting tool). No upgrade fixes it: an admin changes the role. |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
409 | A request with this Idempotency-Key is still running (IDEMPOTENCY_IN_PROGRESS; repeat after Retry-After to collect the result), or it ran and its answer was too large to keep (IDEMPOTENCY_RESULT_NOT_KEPT; it is not run again). |
413 | Request body over 256 KB (BODY_TOO_LARGE). Tool arguments are small JSON objects. |
422 | The tool refused: it needs a confirmation step first (NEEDS_CONFIRMATION), or it declined for another reason it states (TOOL_REFUSED); result holds its explanation. Or this Idempotency-Key was used for a different tool or arguments (IDEMPOTENCY_KEY_REUSED). |
429 | Rate limited: the per-key tool-call limit (Retry-After header set), or the tool refused for a rate cap (e.g. ARTICLE_FAILURE_CAP; body carries the tool result). |
502 | Tool execution failed (TOOL_FAILED) |
503 | Temporarily unavailable, on our side, not a limit: the upstream data provider or the credit check is down (PROVIDER_UNAVAILABLE; nothing was charged), or idempotency is unavailable and the tool was NOT run (IDEMPOTENCY_UNAVAILABLE). Retry shortly. |
504 | The tool is still running past the 60s response ceiling and was not stopped (TOOL_TIMEOUT). With an Idempotency-Key, repeat the request to collect its answer. |
curl -X POST "https://app.seomatic.ai/api/v1/tools/get_keyword_clusters" \
-H "Authorization: Bearer $SEOMATIC_API_KEY"/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 answered. result is its output, usually a JSON string (parse it). A tool that refuses does NOT answer 200: it gets the matching 402/422/429/503 below, with its own output in result. |
400 | Invalid arguments (INVALID_ARGUMENTS; details says what) or a malformed Idempotency-Key (INVALID_IDEMPOTENCY_KEY). |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA); the plan does not include acting through the API (SCOPE_REVOKED_BY_PLAN); X-Seomatic-Client is n8n or make and the workspace has no paid plan or trial (AUTOMATION_NOT_ENTITLED); the free monthly question limit is reached (FREE_QUOTA_EXCEEDED; body carries keep_going_url and a question_pack payment link); the subscription is paused or its card was declined (BILLING_INACTIVE; body links the one step that restores it, never an upgrade); or the tool refused for credits (INSUFFICIENT_CREDITS, PAYMENT_REQUIRED; body carries the tool result); or the tool hit a plan limit (the code is the refusal code itself: PROMPT_LIMIT, CADENCE_LIMIT, MONITOR_LIMIT, PAGE_LIMIT_EXCEEDED, SEAT_LIMIT_EXCEEDED, WORKSPACE_LIMIT_EXCEEDED, PLANNER_DISABLED, AUTO_EXECUTE_DISABLED, AGENT_SKILLS_NOT_ENTITLED, PAGE_TEMPLATES_NOT_ENTITLED, HOSTED_PAGES_NOT_ENTITLED, AI_ATTRIBUTION_NOT_ENTITLED, ZAPIER_NOT_ENTITLED, BYO_KEYS_NOT_ENTITLED, INCREMENTALITY_NOT_ENTITLED, WEBHOOKS_NOT_ENTITLED; `result` holds the tool refusal). Body carries upgrade_url (and reason, for tool refusals) where an upgrade is the fix. |
403 | The plan allows it but the key creator's role in the workspace does not (FORBIDDEN_ROLE; e.g. a creator now a viewer calling an acting tool). No upgrade fixes it: an admin changes the role. |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
409 | A request with this Idempotency-Key is still running (IDEMPOTENCY_IN_PROGRESS; repeat after Retry-After to collect the result), or it ran and its answer was too large to keep (IDEMPOTENCY_RESULT_NOT_KEPT; it is not run again). |
413 | Request body over 256 KB (BODY_TOO_LARGE). Tool arguments are small JSON objects. |
422 | The tool refused: it needs a confirmation step first (NEEDS_CONFIRMATION), or it declined for another reason it states (TOOL_REFUSED); result holds its explanation. Or this Idempotency-Key was used for a different tool or arguments (IDEMPOTENCY_KEY_REUSED). |
429 | Rate limited: the per-key tool-call limit (Retry-After header set), or the tool refused for a rate cap (e.g. ARTICLE_FAILURE_CAP; body carries the tool result). |
502 | Tool execution failed (TOOL_FAILED) |
503 | Temporarily unavailable, on our side, not a limit: the upstream data provider or the credit check is down (PROVIDER_UNAVAILABLE; nothing was charged), or idempotency is unavailable and the tool was NOT run (IDEMPOTENCY_UNAVAILABLE). Retry shortly. |
504 | The tool is still running past the 60s response ceiling and was not stopped (TOOL_TIMEOUT). With an Idempotency-Key, repeat the request to collect its answer. |
curl -X POST "https://app.seomatic.ai/api/v1/tools/get_keyword_trends" \
-H "Authorization: Bearer $SEOMATIC_API_KEY" \
-H "Content-Type: application/json" \
-d '{"keyword":"…"}'/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 answered. result is its output, usually a JSON string (parse it). A tool that refuses does NOT answer 200: it gets the matching 402/422/429/503 below, with its own output in result. |
400 | Invalid arguments (INVALID_ARGUMENTS; details says what) or a malformed Idempotency-Key (INVALID_IDEMPOTENCY_KEY). |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA); the plan does not include acting through the API (SCOPE_REVOKED_BY_PLAN); X-Seomatic-Client is n8n or make and the workspace has no paid plan or trial (AUTOMATION_NOT_ENTITLED); the free monthly question limit is reached (FREE_QUOTA_EXCEEDED; body carries keep_going_url and a question_pack payment link); the subscription is paused or its card was declined (BILLING_INACTIVE; body links the one step that restores it, never an upgrade); or the tool refused for credits (INSUFFICIENT_CREDITS, PAYMENT_REQUIRED; body carries the tool result); or the tool hit a plan limit (the code is the refusal code itself: PROMPT_LIMIT, CADENCE_LIMIT, MONITOR_LIMIT, PAGE_LIMIT_EXCEEDED, SEAT_LIMIT_EXCEEDED, WORKSPACE_LIMIT_EXCEEDED, PLANNER_DISABLED, AUTO_EXECUTE_DISABLED, AGENT_SKILLS_NOT_ENTITLED, PAGE_TEMPLATES_NOT_ENTITLED, HOSTED_PAGES_NOT_ENTITLED, AI_ATTRIBUTION_NOT_ENTITLED, ZAPIER_NOT_ENTITLED, BYO_KEYS_NOT_ENTITLED, INCREMENTALITY_NOT_ENTITLED, WEBHOOKS_NOT_ENTITLED; `result` holds the tool refusal). Body carries upgrade_url (and reason, for tool refusals) where an upgrade is the fix. |
403 | The plan allows it but the key creator's role in the workspace does not (FORBIDDEN_ROLE; e.g. a creator now a viewer calling an acting tool). No upgrade fixes it: an admin changes the role. |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
409 | A request with this Idempotency-Key is still running (IDEMPOTENCY_IN_PROGRESS; repeat after Retry-After to collect the result), or it ran and its answer was too large to keep (IDEMPOTENCY_RESULT_NOT_KEPT; it is not run again). |
413 | Request body over 256 KB (BODY_TOO_LARGE). Tool arguments are small JSON objects. |
422 | The tool refused: it needs a confirmation step first (NEEDS_CONFIRMATION), or it declined for another reason it states (TOOL_REFUSED); result holds its explanation. Or this Idempotency-Key was used for a different tool or arguments (IDEMPOTENCY_KEY_REUSED). |
429 | Rate limited: the per-key tool-call limit (Retry-After header set), or the tool refused for a rate cap (e.g. ARTICLE_FAILURE_CAP; body carries the tool result). |
502 | Tool execution failed (TOOL_FAILED) |
503 | Temporarily unavailable, on our side, not a limit: the upstream data provider or the credit check is down (PROVIDER_UNAVAILABLE; nothing was charged), or idempotency is unavailable and the tool was NOT run (IDEMPOTENCY_UNAVAILABLE). Retry shortly. |
504 | The tool is still running past the 60s response ceiling and was not stopped (TOOL_TIMEOUT). With an Idempotency-Key, repeat the request to collect its answer. |
curl -X POST "https://app.seomatic.ai/api/v1/tools/get_keyword_performance" \
-H "Authorization: Bearer $SEOMATIC_API_KEY"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 answered. result is its output, usually a JSON string (parse it). A tool that refuses does NOT answer 200: it gets the matching 402/422/429/503 below, with its own output in result. |
400 | Invalid arguments (INVALID_ARGUMENTS; details says what) or a malformed Idempotency-Key (INVALID_IDEMPOTENCY_KEY). |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA); the plan does not include acting through the API (SCOPE_REVOKED_BY_PLAN); X-Seomatic-Client is n8n or make and the workspace has no paid plan or trial (AUTOMATION_NOT_ENTITLED); the free monthly question limit is reached (FREE_QUOTA_EXCEEDED; body carries keep_going_url and a question_pack payment link); the subscription is paused or its card was declined (BILLING_INACTIVE; body links the one step that restores it, never an upgrade); or the tool refused for credits (INSUFFICIENT_CREDITS, PAYMENT_REQUIRED; body carries the tool result); or the tool hit a plan limit (the code is the refusal code itself: PROMPT_LIMIT, CADENCE_LIMIT, MONITOR_LIMIT, PAGE_LIMIT_EXCEEDED, SEAT_LIMIT_EXCEEDED, WORKSPACE_LIMIT_EXCEEDED, PLANNER_DISABLED, AUTO_EXECUTE_DISABLED, AGENT_SKILLS_NOT_ENTITLED, PAGE_TEMPLATES_NOT_ENTITLED, HOSTED_PAGES_NOT_ENTITLED, AI_ATTRIBUTION_NOT_ENTITLED, ZAPIER_NOT_ENTITLED, BYO_KEYS_NOT_ENTITLED, INCREMENTALITY_NOT_ENTITLED, WEBHOOKS_NOT_ENTITLED; `result` holds the tool refusal). Body carries upgrade_url (and reason, for tool refusals) where an upgrade is the fix. |
403 | The plan allows it but the key creator's role in the workspace does not (FORBIDDEN_ROLE; e.g. a creator now a viewer calling an acting tool). No upgrade fixes it: an admin changes the role. |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
409 | A request with this Idempotency-Key is still running (IDEMPOTENCY_IN_PROGRESS; repeat after Retry-After to collect the result), or it ran and its answer was too large to keep (IDEMPOTENCY_RESULT_NOT_KEPT; it is not run again). |
413 | Request body over 256 KB (BODY_TOO_LARGE). Tool arguments are small JSON objects. |
422 | The tool refused: it needs a confirmation step first (NEEDS_CONFIRMATION), or it declined for another reason it states (TOOL_REFUSED); result holds its explanation. Or this Idempotency-Key was used for a different tool or arguments (IDEMPOTENCY_KEY_REUSED). |
429 | Rate limited: the per-key tool-call limit (Retry-After header set), or the tool refused for a rate cap (e.g. ARTICLE_FAILURE_CAP; body carries the tool result). |
502 | Tool execution failed (TOOL_FAILED) |
503 | Temporarily unavailable, on our side, not a limit: the upstream data provider or the credit check is down (PROVIDER_UNAVAILABLE; nothing was charged), or idempotency is unavailable and the tool was NOT run (IDEMPOTENCY_UNAVAILABLE). Retry shortly. |
504 | The tool is still running past the 60s response ceiling and was not stopped (TOOL_TIMEOUT). With an Idempotency-Key, repeat the request to collect its answer. |
curl -X POST "https://app.seomatic.ai/api/v1/tools/get_backlink_summary" \
-H "Authorization: Bearer $SEOMATIC_API_KEY" \
-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 answered. result is its output, usually a JSON string (parse it). A tool that refuses does NOT answer 200: it gets the matching 402/422/429/503 below, with its own output in result. |
400 | Invalid arguments (INVALID_ARGUMENTS; details says what) or a malformed Idempotency-Key (INVALID_IDEMPOTENCY_KEY). |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA); the plan does not include acting through the API (SCOPE_REVOKED_BY_PLAN); X-Seomatic-Client is n8n or make and the workspace has no paid plan or trial (AUTOMATION_NOT_ENTITLED); the free monthly question limit is reached (FREE_QUOTA_EXCEEDED; body carries keep_going_url and a question_pack payment link); the subscription is paused or its card was declined (BILLING_INACTIVE; body links the one step that restores it, never an upgrade); or the tool refused for credits (INSUFFICIENT_CREDITS, PAYMENT_REQUIRED; body carries the tool result); or the tool hit a plan limit (the code is the refusal code itself: PROMPT_LIMIT, CADENCE_LIMIT, MONITOR_LIMIT, PAGE_LIMIT_EXCEEDED, SEAT_LIMIT_EXCEEDED, WORKSPACE_LIMIT_EXCEEDED, PLANNER_DISABLED, AUTO_EXECUTE_DISABLED, AGENT_SKILLS_NOT_ENTITLED, PAGE_TEMPLATES_NOT_ENTITLED, HOSTED_PAGES_NOT_ENTITLED, AI_ATTRIBUTION_NOT_ENTITLED, ZAPIER_NOT_ENTITLED, BYO_KEYS_NOT_ENTITLED, INCREMENTALITY_NOT_ENTITLED, WEBHOOKS_NOT_ENTITLED; `result` holds the tool refusal). Body carries upgrade_url (and reason, for tool refusals) where an upgrade is the fix. |
403 | The plan allows it but the key creator's role in the workspace does not (FORBIDDEN_ROLE; e.g. a creator now a viewer calling an acting tool). No upgrade fixes it: an admin changes the role. |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
409 | A request with this Idempotency-Key is still running (IDEMPOTENCY_IN_PROGRESS; repeat after Retry-After to collect the result), or it ran and its answer was too large to keep (IDEMPOTENCY_RESULT_NOT_KEPT; it is not run again). |
413 | Request body over 256 KB (BODY_TOO_LARGE). Tool arguments are small JSON objects. |
422 | The tool refused: it needs a confirmation step first (NEEDS_CONFIRMATION), or it declined for another reason it states (TOOL_REFUSED); result holds its explanation. Or this Idempotency-Key was used for a different tool or arguments (IDEMPOTENCY_KEY_REUSED). |
429 | Rate limited: the per-key tool-call limit (Retry-After header set), or the tool refused for a rate cap (e.g. ARTICLE_FAILURE_CAP; body carries the tool result). |
502 | Tool execution failed (TOOL_FAILED) |
503 | Temporarily unavailable, on our side, not a limit: the upstream data provider or the credit check is down (PROVIDER_UNAVAILABLE; nothing was charged), or idempotency is unavailable and the tool was NOT run (IDEMPOTENCY_UNAVAILABLE). Retry shortly. |
504 | The tool is still running past the 60s response ceiling and was not stopped (TOOL_TIMEOUT). With an Idempotency-Key, repeat the request to collect its answer. |
curl -X POST "https://app.seomatic.ai/api/v1/tools/get_backlink_anchors" \
-H "Authorization: Bearer $SEOMATIC_API_KEY" \
-H "Content-Type: application/json" \
-d '{"domain":"…"}'/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 answered. result is its output, usually a JSON string (parse it). A tool that refuses does NOT answer 200: it gets the matching 402/422/429/503 below, with its own output in result. |
400 | Invalid arguments (INVALID_ARGUMENTS; details says what) or a malformed Idempotency-Key (INVALID_IDEMPOTENCY_KEY). |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA); the plan does not include acting through the API (SCOPE_REVOKED_BY_PLAN); X-Seomatic-Client is n8n or make and the workspace has no paid plan or trial (AUTOMATION_NOT_ENTITLED); the free monthly question limit is reached (FREE_QUOTA_EXCEEDED; body carries keep_going_url and a question_pack payment link); the subscription is paused or its card was declined (BILLING_INACTIVE; body links the one step that restores it, never an upgrade); or the tool refused for credits (INSUFFICIENT_CREDITS, PAYMENT_REQUIRED; body carries the tool result); or the tool hit a plan limit (the code is the refusal code itself: PROMPT_LIMIT, CADENCE_LIMIT, MONITOR_LIMIT, PAGE_LIMIT_EXCEEDED, SEAT_LIMIT_EXCEEDED, WORKSPACE_LIMIT_EXCEEDED, PLANNER_DISABLED, AUTO_EXECUTE_DISABLED, AGENT_SKILLS_NOT_ENTITLED, PAGE_TEMPLATES_NOT_ENTITLED, HOSTED_PAGES_NOT_ENTITLED, AI_ATTRIBUTION_NOT_ENTITLED, ZAPIER_NOT_ENTITLED, BYO_KEYS_NOT_ENTITLED, INCREMENTALITY_NOT_ENTITLED, WEBHOOKS_NOT_ENTITLED; `result` holds the tool refusal). Body carries upgrade_url (and reason, for tool refusals) where an upgrade is the fix. |
403 | The plan allows it but the key creator's role in the workspace does not (FORBIDDEN_ROLE; e.g. a creator now a viewer calling an acting tool). No upgrade fixes it: an admin changes the role. |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
409 | A request with this Idempotency-Key is still running (IDEMPOTENCY_IN_PROGRESS; repeat after Retry-After to collect the result), or it ran and its answer was too large to keep (IDEMPOTENCY_RESULT_NOT_KEPT; it is not run again). |
413 | Request body over 256 KB (BODY_TOO_LARGE). Tool arguments are small JSON objects. |
422 | The tool refused: it needs a confirmation step first (NEEDS_CONFIRMATION), or it declined for another reason it states (TOOL_REFUSED); result holds its explanation. Or this Idempotency-Key was used for a different tool or arguments (IDEMPOTENCY_KEY_REUSED). |
429 | Rate limited: the per-key tool-call limit (Retry-After header set), or the tool refused for a rate cap (e.g. ARTICLE_FAILURE_CAP; body carries the tool result). |
502 | Tool execution failed (TOOL_FAILED) |
503 | Temporarily unavailable, on our side, not a limit: the upstream data provider or the credit check is down (PROVIDER_UNAVAILABLE; nothing was charged), or idempotency is unavailable and the tool was NOT run (IDEMPOTENCY_UNAVAILABLE). Retry shortly. |
504 | The tool is still running past the 60s response ceiling and was not stopped (TOOL_TIMEOUT). With an Idempotency-Key, repeat the request to collect its answer. |
curl -X POST "https://app.seomatic.ai/api/v1/tools/get_backlink_velocity" \
-H "Authorization: Bearer $SEOMATIC_API_KEY" \
-H "Content-Type: application/json" \
-d '{"domain":"…"}'/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 answered. result is its output, usually a JSON string (parse it). A tool that refuses does NOT answer 200: it gets the matching 402/422/429/503 below, with its own output in result. |
400 | Invalid arguments (INVALID_ARGUMENTS; details says what) or a malformed Idempotency-Key (INVALID_IDEMPOTENCY_KEY). |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA); the plan does not include acting through the API (SCOPE_REVOKED_BY_PLAN); X-Seomatic-Client is n8n or make and the workspace has no paid plan or trial (AUTOMATION_NOT_ENTITLED); the free monthly question limit is reached (FREE_QUOTA_EXCEEDED; body carries keep_going_url and a question_pack payment link); the subscription is paused or its card was declined (BILLING_INACTIVE; body links the one step that restores it, never an upgrade); or the tool refused for credits (INSUFFICIENT_CREDITS, PAYMENT_REQUIRED; body carries the tool result); or the tool hit a plan limit (the code is the refusal code itself: PROMPT_LIMIT, CADENCE_LIMIT, MONITOR_LIMIT, PAGE_LIMIT_EXCEEDED, SEAT_LIMIT_EXCEEDED, WORKSPACE_LIMIT_EXCEEDED, PLANNER_DISABLED, AUTO_EXECUTE_DISABLED, AGENT_SKILLS_NOT_ENTITLED, PAGE_TEMPLATES_NOT_ENTITLED, HOSTED_PAGES_NOT_ENTITLED, AI_ATTRIBUTION_NOT_ENTITLED, ZAPIER_NOT_ENTITLED, BYO_KEYS_NOT_ENTITLED, INCREMENTALITY_NOT_ENTITLED, WEBHOOKS_NOT_ENTITLED; `result` holds the tool refusal). Body carries upgrade_url (and reason, for tool refusals) where an upgrade is the fix. |
403 | The plan allows it but the key creator's role in the workspace does not (FORBIDDEN_ROLE; e.g. a creator now a viewer calling an acting tool). No upgrade fixes it: an admin changes the role. |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
409 | A request with this Idempotency-Key is still running (IDEMPOTENCY_IN_PROGRESS; repeat after Retry-After to collect the result), or it ran and its answer was too large to keep (IDEMPOTENCY_RESULT_NOT_KEPT; it is not run again). |
413 | Request body over 256 KB (BODY_TOO_LARGE). Tool arguments are small JSON objects. |
422 | The tool refused: it needs a confirmation step first (NEEDS_CONFIRMATION), or it declined for another reason it states (TOOL_REFUSED); result holds its explanation. Or this Idempotency-Key was used for a different tool or arguments (IDEMPOTENCY_KEY_REUSED). |
429 | Rate limited: the per-key tool-call limit (Retry-After header set), or the tool refused for a rate cap (e.g. ARTICLE_FAILURE_CAP; body carries the tool result). |
502 | Tool execution failed (TOOL_FAILED) |
503 | Temporarily unavailable, on our side, not a limit: the upstream data provider or the credit check is down (PROVIDER_UNAVAILABLE; nothing was charged), or idempotency is unavailable and the tool was NOT run (IDEMPOTENCY_UNAVAILABLE). Retry shortly. |
504 | The tool is still running past the 60s response ceiling and was not stopped (TOOL_TIMEOUT). With an Idempotency-Key, repeat the request to collect its answer. |
curl -X POST "https://app.seomatic.ai/api/v1/tools/get_referring_domains" \
-H "Authorization: Bearer $SEOMATIC_API_KEY" \
-H "Content-Type: application/json" \
-d '{"domain":"…"}'/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 answered. result is its output, usually a JSON string (parse it). A tool that refuses does NOT answer 200: it gets the matching 402/422/429/503 below, with its own output in result. |
400 | Invalid arguments (INVALID_ARGUMENTS; details says what) or a malformed Idempotency-Key (INVALID_IDEMPOTENCY_KEY). |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA); the plan does not include acting through the API (SCOPE_REVOKED_BY_PLAN); X-Seomatic-Client is n8n or make and the workspace has no paid plan or trial (AUTOMATION_NOT_ENTITLED); the free monthly question limit is reached (FREE_QUOTA_EXCEEDED; body carries keep_going_url and a question_pack payment link); the subscription is paused or its card was declined (BILLING_INACTIVE; body links the one step that restores it, never an upgrade); or the tool refused for credits (INSUFFICIENT_CREDITS, PAYMENT_REQUIRED; body carries the tool result); or the tool hit a plan limit (the code is the refusal code itself: PROMPT_LIMIT, CADENCE_LIMIT, MONITOR_LIMIT, PAGE_LIMIT_EXCEEDED, SEAT_LIMIT_EXCEEDED, WORKSPACE_LIMIT_EXCEEDED, PLANNER_DISABLED, AUTO_EXECUTE_DISABLED, AGENT_SKILLS_NOT_ENTITLED, PAGE_TEMPLATES_NOT_ENTITLED, HOSTED_PAGES_NOT_ENTITLED, AI_ATTRIBUTION_NOT_ENTITLED, ZAPIER_NOT_ENTITLED, BYO_KEYS_NOT_ENTITLED, INCREMENTALITY_NOT_ENTITLED, WEBHOOKS_NOT_ENTITLED; `result` holds the tool refusal). Body carries upgrade_url (and reason, for tool refusals) where an upgrade is the fix. |
403 | The plan allows it but the key creator's role in the workspace does not (FORBIDDEN_ROLE; e.g. a creator now a viewer calling an acting tool). No upgrade fixes it: an admin changes the role. |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
409 | A request with this Idempotency-Key is still running (IDEMPOTENCY_IN_PROGRESS; repeat after Retry-After to collect the result), or it ran and its answer was too large to keep (IDEMPOTENCY_RESULT_NOT_KEPT; it is not run again). |
413 | Request body over 256 KB (BODY_TOO_LARGE). Tool arguments are small JSON objects. |
422 | The tool refused: it needs a confirmation step first (NEEDS_CONFIRMATION), or it declined for another reason it states (TOOL_REFUSED); result holds its explanation. Or this Idempotency-Key was used for a different tool or arguments (IDEMPOTENCY_KEY_REUSED). |
429 | Rate limited: the per-key tool-call limit (Retry-After header set), or the tool refused for a rate cap (e.g. ARTICLE_FAILURE_CAP; body carries the tool result). |
502 | Tool execution failed (TOOL_FAILED) |
503 | Temporarily unavailable, on our side, not a limit: the upstream data provider or the credit check is down (PROVIDER_UNAVAILABLE; nothing was charged), or idempotency is unavailable and the tool was NOT run (IDEMPOTENCY_UNAVAILABLE). Retry shortly. |
504 | The tool is still running past the 60s response ceiling and was not stopped (TOOL_TIMEOUT). With an Idempotency-Key, repeat the request to collect its answer. |
curl -X POST "https://app.seomatic.ai/api/v1/tools/find_link_prospects" \
-H "Authorization: Bearer $SEOMATIC_API_KEY" \
-H "Content-Type: application/json" \
-d '{"competitors":[]}'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) |
location_code | number | no | Location code (default: the site's own market). Examples: 2840 US, 2826 UK, 2250 France, 2276 Germany. |
language_code | string | no | Language code (default: the site's own language). Examples: "en", "fr", "de". |
| Status | Description |
|---|---|
200 | { tool, result }: the tool answered. result is its output, usually a JSON string (parse it). A tool that refuses does NOT answer 200: it gets the matching 402/422/429/503 below, with its own output in result. |
400 | Invalid arguments (INVALID_ARGUMENTS; details says what) or a malformed Idempotency-Key (INVALID_IDEMPOTENCY_KEY). |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA); the plan does not include acting through the API (SCOPE_REVOKED_BY_PLAN); X-Seomatic-Client is n8n or make and the workspace has no paid plan or trial (AUTOMATION_NOT_ENTITLED); the free monthly question limit is reached (FREE_QUOTA_EXCEEDED; body carries keep_going_url and a question_pack payment link); the subscription is paused or its card was declined (BILLING_INACTIVE; body links the one step that restores it, never an upgrade); or the tool refused for credits (INSUFFICIENT_CREDITS, PAYMENT_REQUIRED; body carries the tool result); or the tool hit a plan limit (the code is the refusal code itself: PROMPT_LIMIT, CADENCE_LIMIT, MONITOR_LIMIT, PAGE_LIMIT_EXCEEDED, SEAT_LIMIT_EXCEEDED, WORKSPACE_LIMIT_EXCEEDED, PLANNER_DISABLED, AUTO_EXECUTE_DISABLED, AGENT_SKILLS_NOT_ENTITLED, PAGE_TEMPLATES_NOT_ENTITLED, HOSTED_PAGES_NOT_ENTITLED, AI_ATTRIBUTION_NOT_ENTITLED, ZAPIER_NOT_ENTITLED, BYO_KEYS_NOT_ENTITLED, INCREMENTALITY_NOT_ENTITLED, WEBHOOKS_NOT_ENTITLED; `result` holds the tool refusal). Body carries upgrade_url (and reason, for tool refusals) where an upgrade is the fix. |
403 | The plan allows it but the key creator's role in the workspace does not (FORBIDDEN_ROLE; e.g. a creator now a viewer calling an acting tool). No upgrade fixes it: an admin changes the role. |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
409 | A request with this Idempotency-Key is still running (IDEMPOTENCY_IN_PROGRESS; repeat after Retry-After to collect the result), or it ran and its answer was too large to keep (IDEMPOTENCY_RESULT_NOT_KEPT; it is not run again). |
413 | Request body over 256 KB (BODY_TOO_LARGE). Tool arguments are small JSON objects. |
422 | The tool refused: it needs a confirmation step first (NEEDS_CONFIRMATION), or it declined for another reason it states (TOOL_REFUSED); result holds its explanation. Or this Idempotency-Key was used for a different tool or arguments (IDEMPOTENCY_KEY_REUSED). |
429 | Rate limited: the per-key tool-call limit (Retry-After header set), or the tool refused for a rate cap (e.g. ARTICLE_FAILURE_CAP; body carries the tool result). |
502 | Tool execution failed (TOOL_FAILED) |
503 | Temporarily unavailable, on our side, not a limit: the upstream data provider or the credit check is down (PROVIDER_UNAVAILABLE; nothing was charged), or idempotency is unavailable and the tool was NOT run (IDEMPOTENCY_UNAVAILABLE). Retry shortly. |
504 | The tool is still running past the 60s response ceiling and was not stopped (TOOL_TIMEOUT). With an Idempotency-Key, repeat the request to collect its answer. |
curl -X POST "https://app.seomatic.ai/api/v1/tools/get_serp_features" \
-H "Authorization: Bearer $SEOMATIC_API_KEY" \
-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: the site's own market). |
language_code | string | no | Language code (default: the site's own language). |
| Status | Description |
|---|---|
200 | { tool, result }: the tool answered. result is its output, usually a JSON string (parse it). A tool that refuses does NOT answer 200: it gets the matching 402/422/429/503 below, with its own output in result. |
400 | Invalid arguments (INVALID_ARGUMENTS; details says what) or a malformed Idempotency-Key (INVALID_IDEMPOTENCY_KEY). |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA); the plan does not include acting through the API (SCOPE_REVOKED_BY_PLAN); X-Seomatic-Client is n8n or make and the workspace has no paid plan or trial (AUTOMATION_NOT_ENTITLED); the free monthly question limit is reached (FREE_QUOTA_EXCEEDED; body carries keep_going_url and a question_pack payment link); the subscription is paused or its card was declined (BILLING_INACTIVE; body links the one step that restores it, never an upgrade); or the tool refused for credits (INSUFFICIENT_CREDITS, PAYMENT_REQUIRED; body carries the tool result); or the tool hit a plan limit (the code is the refusal code itself: PROMPT_LIMIT, CADENCE_LIMIT, MONITOR_LIMIT, PAGE_LIMIT_EXCEEDED, SEAT_LIMIT_EXCEEDED, WORKSPACE_LIMIT_EXCEEDED, PLANNER_DISABLED, AUTO_EXECUTE_DISABLED, AGENT_SKILLS_NOT_ENTITLED, PAGE_TEMPLATES_NOT_ENTITLED, HOSTED_PAGES_NOT_ENTITLED, AI_ATTRIBUTION_NOT_ENTITLED, ZAPIER_NOT_ENTITLED, BYO_KEYS_NOT_ENTITLED, INCREMENTALITY_NOT_ENTITLED, WEBHOOKS_NOT_ENTITLED; `result` holds the tool refusal). Body carries upgrade_url (and reason, for tool refusals) where an upgrade is the fix. |
403 | The plan allows it but the key creator's role in the workspace does not (FORBIDDEN_ROLE; e.g. a creator now a viewer calling an acting tool). No upgrade fixes it: an admin changes the role. |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
409 | A request with this Idempotency-Key is still running (IDEMPOTENCY_IN_PROGRESS; repeat after Retry-After to collect the result), or it ran and its answer was too large to keep (IDEMPOTENCY_RESULT_NOT_KEPT; it is not run again). |
413 | Request body over 256 KB (BODY_TOO_LARGE). Tool arguments are small JSON objects. |
422 | The tool refused: it needs a confirmation step first (NEEDS_CONFIRMATION), or it declined for another reason it states (TOOL_REFUSED); result holds its explanation. Or this Idempotency-Key was used for a different tool or arguments (IDEMPOTENCY_KEY_REUSED). |
429 | Rate limited: the per-key tool-call limit (Retry-After header set), or the tool refused for a rate cap (e.g. ARTICLE_FAILURE_CAP; body carries the tool result). |
502 | Tool execution failed (TOOL_FAILED) |
503 | Temporarily unavailable, on our side, not a limit: the upstream data provider or the credit check is down (PROVIDER_UNAVAILABLE; nothing was charged), or idempotency is unavailable and the tool was NOT run (IDEMPOTENCY_UNAVAILABLE). Retry shortly. |
504 | The tool is still running past the 60s response ceiling and was not stopped (TOOL_TIMEOUT). With an Idempotency-Key, repeat the request to collect its answer. |
curl -X POST "https://app.seomatic.ai/api/v1/tools/get_domain_rankings" \
-H "Authorization: Bearer $SEOMATIC_API_KEY" \
-H "Content-Type: application/json" \
-d '{"domain":"…"}'/tools/get_domain_overviewreadGet an overview of a domain's SEO visibility including organic ranking distribution (keywords at position 1, positions 2-3, 4-10 and so on, plus true top-3 and top-10 totals), estimated traffic volum…
| Name | Type | Required | Description |
|---|---|---|---|
domain | string | yes | The domain to analyze (e.g., "backmarket.com") |
location_code | number | no | Location code (default: the site's own market). |
language_code | string | no | Language code (default: the site's own language). |
| Status | Description |
|---|---|
200 | { tool, result }: the tool answered. result is its output, usually a JSON string (parse it). A tool that refuses does NOT answer 200: it gets the matching 402/422/429/503 below, with its own output in result. |
400 | Invalid arguments (INVALID_ARGUMENTS; details says what) or a malformed Idempotency-Key (INVALID_IDEMPOTENCY_KEY). |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA); the plan does not include acting through the API (SCOPE_REVOKED_BY_PLAN); X-Seomatic-Client is n8n or make and the workspace has no paid plan or trial (AUTOMATION_NOT_ENTITLED); the free monthly question limit is reached (FREE_QUOTA_EXCEEDED; body carries keep_going_url and a question_pack payment link); the subscription is paused or its card was declined (BILLING_INACTIVE; body links the one step that restores it, never an upgrade); or the tool refused for credits (INSUFFICIENT_CREDITS, PAYMENT_REQUIRED; body carries the tool result); or the tool hit a plan limit (the code is the refusal code itself: PROMPT_LIMIT, CADENCE_LIMIT, MONITOR_LIMIT, PAGE_LIMIT_EXCEEDED, SEAT_LIMIT_EXCEEDED, WORKSPACE_LIMIT_EXCEEDED, PLANNER_DISABLED, AUTO_EXECUTE_DISABLED, AGENT_SKILLS_NOT_ENTITLED, PAGE_TEMPLATES_NOT_ENTITLED, HOSTED_PAGES_NOT_ENTITLED, AI_ATTRIBUTION_NOT_ENTITLED, ZAPIER_NOT_ENTITLED, BYO_KEYS_NOT_ENTITLED, INCREMENTALITY_NOT_ENTITLED, WEBHOOKS_NOT_ENTITLED; `result` holds the tool refusal). Body carries upgrade_url (and reason, for tool refusals) where an upgrade is the fix. |
403 | The plan allows it but the key creator's role in the workspace does not (FORBIDDEN_ROLE; e.g. a creator now a viewer calling an acting tool). No upgrade fixes it: an admin changes the role. |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
409 | A request with this Idempotency-Key is still running (IDEMPOTENCY_IN_PROGRESS; repeat after Retry-After to collect the result), or it ran and its answer was too large to keep (IDEMPOTENCY_RESULT_NOT_KEPT; it is not run again). |
413 | Request body over 256 KB (BODY_TOO_LARGE). Tool arguments are small JSON objects. |
422 | The tool refused: it needs a confirmation step first (NEEDS_CONFIRMATION), or it declined for another reason it states (TOOL_REFUSED); result holds its explanation. Or this Idempotency-Key was used for a different tool or arguments (IDEMPOTENCY_KEY_REUSED). |
429 | Rate limited: the per-key tool-call limit (Retry-After header set), or the tool refused for a rate cap (e.g. ARTICLE_FAILURE_CAP; body carries the tool result). |
502 | Tool execution failed (TOOL_FAILED) |
503 | Temporarily unavailable, on our side, not a limit: the upstream data provider or the credit check is down (PROVIDER_UNAVAILABLE; nothing was charged), or idempotency is unavailable and the tool was NOT run (IDEMPOTENCY_UNAVAILABLE). Retry shortly. |
504 | The tool is still running past the 60s response ceiling and was not stopped (TOOL_TIMEOUT). With an Idempotency-Key, repeat the request to collect its answer. |
curl -X POST "https://app.seomatic.ai/api/v1/tools/get_domain_overview" \
-H "Authorization: Bearer $SEOMATIC_API_KEY" \
-H "Content-Type: application/json" \
-d '{"domain":"…"}'/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: the site's own market). |
language_code | string | no | Language code (default: the site's own language). |
| Status | Description |
|---|---|
200 | { tool, result }: the tool answered. result is its output, usually a JSON string (parse it). A tool that refuses does NOT answer 200: it gets the matching 402/422/429/503 below, with its own output in result. |
400 | Invalid arguments (INVALID_ARGUMENTS; details says what) or a malformed Idempotency-Key (INVALID_IDEMPOTENCY_KEY). |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA); the plan does not include acting through the API (SCOPE_REVOKED_BY_PLAN); X-Seomatic-Client is n8n or make and the workspace has no paid plan or trial (AUTOMATION_NOT_ENTITLED); the free monthly question limit is reached (FREE_QUOTA_EXCEEDED; body carries keep_going_url and a question_pack payment link); the subscription is paused or its card was declined (BILLING_INACTIVE; body links the one step that restores it, never an upgrade); or the tool refused for credits (INSUFFICIENT_CREDITS, PAYMENT_REQUIRED; body carries the tool result); or the tool hit a plan limit (the code is the refusal code itself: PROMPT_LIMIT, CADENCE_LIMIT, MONITOR_LIMIT, PAGE_LIMIT_EXCEEDED, SEAT_LIMIT_EXCEEDED, WORKSPACE_LIMIT_EXCEEDED, PLANNER_DISABLED, AUTO_EXECUTE_DISABLED, AGENT_SKILLS_NOT_ENTITLED, PAGE_TEMPLATES_NOT_ENTITLED, HOSTED_PAGES_NOT_ENTITLED, AI_ATTRIBUTION_NOT_ENTITLED, ZAPIER_NOT_ENTITLED, BYO_KEYS_NOT_ENTITLED, INCREMENTALITY_NOT_ENTITLED, WEBHOOKS_NOT_ENTITLED; `result` holds the tool refusal). Body carries upgrade_url (and reason, for tool refusals) where an upgrade is the fix. |
403 | The plan allows it but the key creator's role in the workspace does not (FORBIDDEN_ROLE; e.g. a creator now a viewer calling an acting tool). No upgrade fixes it: an admin changes the role. |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
409 | A request with this Idempotency-Key is still running (IDEMPOTENCY_IN_PROGRESS; repeat after Retry-After to collect the result), or it ran and its answer was too large to keep (IDEMPOTENCY_RESULT_NOT_KEPT; it is not run again). |
413 | Request body over 256 KB (BODY_TOO_LARGE). Tool arguments are small JSON objects. |
422 | The tool refused: it needs a confirmation step first (NEEDS_CONFIRMATION), or it declined for another reason it states (TOOL_REFUSED); result holds its explanation. Or this Idempotency-Key was used for a different tool or arguments (IDEMPOTENCY_KEY_REUSED). |
429 | Rate limited: the per-key tool-call limit (Retry-After header set), or the tool refused for a rate cap (e.g. ARTICLE_FAILURE_CAP; body carries the tool result). |
502 | Tool execution failed (TOOL_FAILED) |
503 | Temporarily unavailable, on our side, not a limit: the upstream data provider or the credit check is down (PROVIDER_UNAVAILABLE; nothing was charged), or idempotency is unavailable and the tool was NOT run (IDEMPOTENCY_UNAVAILABLE). Retry shortly. |
504 | The tool is still running past the 60s response ceiling and was not stopped (TOOL_TIMEOUT). With an Idempotency-Key, repeat the request to collect its answer. |
curl -X POST "https://app.seomatic.ai/api/v1/tools/get_domain_competitors" \
-H "Authorization: Bearer $SEOMATIC_API_KEY" \
-H "Content-Type: application/json" \
-d '{"domain":"…"}'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 answered. result is its output, usually a JSON string (parse it). A tool that refuses does NOT answer 200: it gets the matching 402/422/429/503 below, with its own output in result. |
400 | Invalid arguments (INVALID_ARGUMENTS; details says what) or a malformed Idempotency-Key (INVALID_IDEMPOTENCY_KEY). |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA); the plan does not include acting through the API (SCOPE_REVOKED_BY_PLAN); X-Seomatic-Client is n8n or make and the workspace has no paid plan or trial (AUTOMATION_NOT_ENTITLED); the free monthly question limit is reached (FREE_QUOTA_EXCEEDED; body carries keep_going_url and a question_pack payment link); the subscription is paused or its card was declined (BILLING_INACTIVE; body links the one step that restores it, never an upgrade); or the tool refused for credits (INSUFFICIENT_CREDITS, PAYMENT_REQUIRED; body carries the tool result); or the tool hit a plan limit (the code is the refusal code itself: PROMPT_LIMIT, CADENCE_LIMIT, MONITOR_LIMIT, PAGE_LIMIT_EXCEEDED, SEAT_LIMIT_EXCEEDED, WORKSPACE_LIMIT_EXCEEDED, PLANNER_DISABLED, AUTO_EXECUTE_DISABLED, AGENT_SKILLS_NOT_ENTITLED, PAGE_TEMPLATES_NOT_ENTITLED, HOSTED_PAGES_NOT_ENTITLED, AI_ATTRIBUTION_NOT_ENTITLED, ZAPIER_NOT_ENTITLED, BYO_KEYS_NOT_ENTITLED, INCREMENTALITY_NOT_ENTITLED, WEBHOOKS_NOT_ENTITLED; `result` holds the tool refusal). Body carries upgrade_url (and reason, for tool refusals) where an upgrade is the fix. |
403 | The plan allows it but the key creator's role in the workspace does not (FORBIDDEN_ROLE; e.g. a creator now a viewer calling an acting tool). No upgrade fixes it: an admin changes the role. |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
409 | A request with this Idempotency-Key is still running (IDEMPOTENCY_IN_PROGRESS; repeat after Retry-After to collect the result), or it ran and its answer was too large to keep (IDEMPOTENCY_RESULT_NOT_KEPT; it is not run again). |
413 | Request body over 256 KB (BODY_TOO_LARGE). Tool arguments are small JSON objects. |
422 | The tool refused: it needs a confirmation step first (NEEDS_CONFIRMATION), or it declined for another reason it states (TOOL_REFUSED); result holds its explanation. Or this Idempotency-Key was used for a different tool or arguments (IDEMPOTENCY_KEY_REUSED). |
429 | Rate limited: the per-key tool-call limit (Retry-After header set), or the tool refused for a rate cap (e.g. ARTICLE_FAILURE_CAP; body carries the tool result). |
502 | Tool execution failed (TOOL_FAILED) |
503 | Temporarily unavailable, on our side, not a limit: the upstream data provider or the credit check is down (PROVIDER_UNAVAILABLE; nothing was charged), or idempotency is unavailable and the tool was NOT run (IDEMPOTENCY_UNAVAILABLE). Retry shortly. |
504 | The tool is still running past the 60s response ceiling and was not stopped (TOOL_TIMEOUT). With an Idempotency-Key, repeat the request to collect its answer. |
curl -X POST "https://app.seomatic.ai/api/v1/tools/get_traffic_overview" \
-H "Authorization: Bearer $SEOMATIC_API_KEY"/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 answered. result is its output, usually a JSON string (parse it). A tool that refuses does NOT answer 200: it gets the matching 402/422/429/503 below, with its own output in result. |
400 | Invalid arguments (INVALID_ARGUMENTS; details says what) or a malformed Idempotency-Key (INVALID_IDEMPOTENCY_KEY). |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA); the plan does not include acting through the API (SCOPE_REVOKED_BY_PLAN); X-Seomatic-Client is n8n or make and the workspace has no paid plan or trial (AUTOMATION_NOT_ENTITLED); the free monthly question limit is reached (FREE_QUOTA_EXCEEDED; body carries keep_going_url and a question_pack payment link); the subscription is paused or its card was declined (BILLING_INACTIVE; body links the one step that restores it, never an upgrade); or the tool refused for credits (INSUFFICIENT_CREDITS, PAYMENT_REQUIRED; body carries the tool result); or the tool hit a plan limit (the code is the refusal code itself: PROMPT_LIMIT, CADENCE_LIMIT, MONITOR_LIMIT, PAGE_LIMIT_EXCEEDED, SEAT_LIMIT_EXCEEDED, WORKSPACE_LIMIT_EXCEEDED, PLANNER_DISABLED, AUTO_EXECUTE_DISABLED, AGENT_SKILLS_NOT_ENTITLED, PAGE_TEMPLATES_NOT_ENTITLED, HOSTED_PAGES_NOT_ENTITLED, AI_ATTRIBUTION_NOT_ENTITLED, ZAPIER_NOT_ENTITLED, BYO_KEYS_NOT_ENTITLED, INCREMENTALITY_NOT_ENTITLED, WEBHOOKS_NOT_ENTITLED; `result` holds the tool refusal). Body carries upgrade_url (and reason, for tool refusals) where an upgrade is the fix. |
403 | The plan allows it but the key creator's role in the workspace does not (FORBIDDEN_ROLE; e.g. a creator now a viewer calling an acting tool). No upgrade fixes it: an admin changes the role. |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
409 | A request with this Idempotency-Key is still running (IDEMPOTENCY_IN_PROGRESS; repeat after Retry-After to collect the result), or it ran and its answer was too large to keep (IDEMPOTENCY_RESULT_NOT_KEPT; it is not run again). |
413 | Request body over 256 KB (BODY_TOO_LARGE). Tool arguments are small JSON objects. |
422 | The tool refused: it needs a confirmation step first (NEEDS_CONFIRMATION), or it declined for another reason it states (TOOL_REFUSED); result holds its explanation. Or this Idempotency-Key was used for a different tool or arguments (IDEMPOTENCY_KEY_REUSED). |
429 | Rate limited: the per-key tool-call limit (Retry-After header set), or the tool refused for a rate cap (e.g. ARTICLE_FAILURE_CAP; body carries the tool result). |
502 | Tool execution failed (TOOL_FAILED) |
503 | Temporarily unavailable, on our side, not a limit: the upstream data provider or the credit check is down (PROVIDER_UNAVAILABLE; nothing was charged), or idempotency is unavailable and the tool was NOT run (IDEMPOTENCY_UNAVAILABLE). Retry shortly. |
504 | The tool is still running past the 60s response ceiling and was not stopped (TOOL_TIMEOUT). With an Idempotency-Key, repeat the request to collect its answer. |
curl -X POST "https://app.seomatic.ai/api/v1/tools/get_traffic_sources" \
-H "Authorization: Bearer $SEOMATIC_API_KEY"/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 answered. result is its output, usually a JSON string (parse it). A tool that refuses does NOT answer 200: it gets the matching 402/422/429/503 below, with its own output in result. |
400 | Invalid arguments (INVALID_ARGUMENTS; details says what) or a malformed Idempotency-Key (INVALID_IDEMPOTENCY_KEY). |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA); the plan does not include acting through the API (SCOPE_REVOKED_BY_PLAN); X-Seomatic-Client is n8n or make and the workspace has no paid plan or trial (AUTOMATION_NOT_ENTITLED); the free monthly question limit is reached (FREE_QUOTA_EXCEEDED; body carries keep_going_url and a question_pack payment link); the subscription is paused or its card was declined (BILLING_INACTIVE; body links the one step that restores it, never an upgrade); or the tool refused for credits (INSUFFICIENT_CREDITS, PAYMENT_REQUIRED; body carries the tool result); or the tool hit a plan limit (the code is the refusal code itself: PROMPT_LIMIT, CADENCE_LIMIT, MONITOR_LIMIT, PAGE_LIMIT_EXCEEDED, SEAT_LIMIT_EXCEEDED, WORKSPACE_LIMIT_EXCEEDED, PLANNER_DISABLED, AUTO_EXECUTE_DISABLED, AGENT_SKILLS_NOT_ENTITLED, PAGE_TEMPLATES_NOT_ENTITLED, HOSTED_PAGES_NOT_ENTITLED, AI_ATTRIBUTION_NOT_ENTITLED, ZAPIER_NOT_ENTITLED, BYO_KEYS_NOT_ENTITLED, INCREMENTALITY_NOT_ENTITLED, WEBHOOKS_NOT_ENTITLED; `result` holds the tool refusal). Body carries upgrade_url (and reason, for tool refusals) where an upgrade is the fix. |
403 | The plan allows it but the key creator's role in the workspace does not (FORBIDDEN_ROLE; e.g. a creator now a viewer calling an acting tool). No upgrade fixes it: an admin changes the role. |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
409 | A request with this Idempotency-Key is still running (IDEMPOTENCY_IN_PROGRESS; repeat after Retry-After to collect the result), or it ran and its answer was too large to keep (IDEMPOTENCY_RESULT_NOT_KEPT; it is not run again). |
413 | Request body over 256 KB (BODY_TOO_LARGE). Tool arguments are small JSON objects. |
422 | The tool refused: it needs a confirmation step first (NEEDS_CONFIRMATION), or it declined for another reason it states (TOOL_REFUSED); result holds its explanation. Or this Idempotency-Key was used for a different tool or arguments (IDEMPOTENCY_KEY_REUSED). |
429 | Rate limited: the per-key tool-call limit (Retry-After header set), or the tool refused for a rate cap (e.g. ARTICLE_FAILURE_CAP; body carries the tool result). |
502 | Tool execution failed (TOOL_FAILED) |
503 | Temporarily unavailable, on our side, not a limit: the upstream data provider or the credit check is down (PROVIDER_UNAVAILABLE; nothing was charged), or idempotency is unavailable and the tool was NOT run (IDEMPOTENCY_UNAVAILABLE). Retry shortly. |
504 | The tool is still running past the 60s response ceiling and was not stopped (TOOL_TIMEOUT). With an Idempotency-Key, repeat the request to collect its answer. |
curl -X POST "https://app.seomatic.ai/api/v1/tools/get_landing_pages" \
-H "Authorization: Bearer $SEOMATIC_API_KEY"/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 answered. result is its output, usually a JSON string (parse it). A tool that refuses does NOT answer 200: it gets the matching 402/422/429/503 below, with its own output in result. |
400 | Invalid arguments (INVALID_ARGUMENTS; details says what) or a malformed Idempotency-Key (INVALID_IDEMPOTENCY_KEY). |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA); the plan does not include acting through the API (SCOPE_REVOKED_BY_PLAN); X-Seomatic-Client is n8n or make and the workspace has no paid plan or trial (AUTOMATION_NOT_ENTITLED); the free monthly question limit is reached (FREE_QUOTA_EXCEEDED; body carries keep_going_url and a question_pack payment link); the subscription is paused or its card was declined (BILLING_INACTIVE; body links the one step that restores it, never an upgrade); or the tool refused for credits (INSUFFICIENT_CREDITS, PAYMENT_REQUIRED; body carries the tool result); or the tool hit a plan limit (the code is the refusal code itself: PROMPT_LIMIT, CADENCE_LIMIT, MONITOR_LIMIT, PAGE_LIMIT_EXCEEDED, SEAT_LIMIT_EXCEEDED, WORKSPACE_LIMIT_EXCEEDED, PLANNER_DISABLED, AUTO_EXECUTE_DISABLED, AGENT_SKILLS_NOT_ENTITLED, PAGE_TEMPLATES_NOT_ENTITLED, HOSTED_PAGES_NOT_ENTITLED, AI_ATTRIBUTION_NOT_ENTITLED, ZAPIER_NOT_ENTITLED, BYO_KEYS_NOT_ENTITLED, INCREMENTALITY_NOT_ENTITLED, WEBHOOKS_NOT_ENTITLED; `result` holds the tool refusal). Body carries upgrade_url (and reason, for tool refusals) where an upgrade is the fix. |
403 | The plan allows it but the key creator's role in the workspace does not (FORBIDDEN_ROLE; e.g. a creator now a viewer calling an acting tool). No upgrade fixes it: an admin changes the role. |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
409 | A request with this Idempotency-Key is still running (IDEMPOTENCY_IN_PROGRESS; repeat after Retry-After to collect the result), or it ran and its answer was too large to keep (IDEMPOTENCY_RESULT_NOT_KEPT; it is not run again). |
413 | Request body over 256 KB (BODY_TOO_LARGE). Tool arguments are small JSON objects. |
422 | The tool refused: it needs a confirmation step first (NEEDS_CONFIRMATION), or it declined for another reason it states (TOOL_REFUSED); result holds its explanation. Or this Idempotency-Key was used for a different tool or arguments (IDEMPOTENCY_KEY_REUSED). |
429 | Rate limited: the per-key tool-call limit (Retry-After header set), or the tool refused for a rate cap (e.g. ARTICLE_FAILURE_CAP; body carries the tool result). |
502 | Tool execution failed (TOOL_FAILED) |
503 | Temporarily unavailable, on our side, not a limit: the upstream data provider or the credit check is down (PROVIDER_UNAVAILABLE; nothing was charged), or idempotency is unavailable and the tool was NOT run (IDEMPOTENCY_UNAVAILABLE). Retry shortly. |
504 | The tool is still running past the 60s response ceiling and was not stopped (TOOL_TIMEOUT). With an Idempotency-Key, repeat the request to collect its answer. |
curl -X POST "https://app.seomatic.ai/api/v1/tools/get_top_viewed_pages" \
-H "Authorization: Bearer $SEOMATIC_API_KEY"/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 answered. result is its output, usually a JSON string (parse it). A tool that refuses does NOT answer 200: it gets the matching 402/422/429/503 below, with its own output in result. |
400 | Invalid arguments (INVALID_ARGUMENTS; details says what) or a malformed Idempotency-Key (INVALID_IDEMPOTENCY_KEY). |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA); the plan does not include acting through the API (SCOPE_REVOKED_BY_PLAN); X-Seomatic-Client is n8n or make and the workspace has no paid plan or trial (AUTOMATION_NOT_ENTITLED); the free monthly question limit is reached (FREE_QUOTA_EXCEEDED; body carries keep_going_url and a question_pack payment link); the subscription is paused or its card was declined (BILLING_INACTIVE; body links the one step that restores it, never an upgrade); or the tool refused for credits (INSUFFICIENT_CREDITS, PAYMENT_REQUIRED; body carries the tool result); or the tool hit a plan limit (the code is the refusal code itself: PROMPT_LIMIT, CADENCE_LIMIT, MONITOR_LIMIT, PAGE_LIMIT_EXCEEDED, SEAT_LIMIT_EXCEEDED, WORKSPACE_LIMIT_EXCEEDED, PLANNER_DISABLED, AUTO_EXECUTE_DISABLED, AGENT_SKILLS_NOT_ENTITLED, PAGE_TEMPLATES_NOT_ENTITLED, HOSTED_PAGES_NOT_ENTITLED, AI_ATTRIBUTION_NOT_ENTITLED, ZAPIER_NOT_ENTITLED, BYO_KEYS_NOT_ENTITLED, INCREMENTALITY_NOT_ENTITLED, WEBHOOKS_NOT_ENTITLED; `result` holds the tool refusal). Body carries upgrade_url (and reason, for tool refusals) where an upgrade is the fix. |
403 | The plan allows it but the key creator's role in the workspace does not (FORBIDDEN_ROLE; e.g. a creator now a viewer calling an acting tool). No upgrade fixes it: an admin changes the role. |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
409 | A request with this Idempotency-Key is still running (IDEMPOTENCY_IN_PROGRESS; repeat after Retry-After to collect the result), or it ran and its answer was too large to keep (IDEMPOTENCY_RESULT_NOT_KEPT; it is not run again). |
413 | Request body over 256 KB (BODY_TOO_LARGE). Tool arguments are small JSON objects. |
422 | The tool refused: it needs a confirmation step first (NEEDS_CONFIRMATION), or it declined for another reason it states (TOOL_REFUSED); result holds its explanation. Or this Idempotency-Key was used for a different tool or arguments (IDEMPOTENCY_KEY_REUSED). |
429 | Rate limited: the per-key tool-call limit (Retry-After header set), or the tool refused for a rate cap (e.g. ARTICLE_FAILURE_CAP; body carries the tool result). |
502 | Tool execution failed (TOOL_FAILED) |
503 | Temporarily unavailable, on our side, not a limit: the upstream data provider or the credit check is down (PROVIDER_UNAVAILABLE; nothing was charged), or idempotency is unavailable and the tool was NOT run (IDEMPOTENCY_UNAVAILABLE). Retry shortly. |
504 | The tool is still running past the 60s response ceiling and was not stopped (TOOL_TIMEOUT). With an Idempotency-Key, repeat the request to collect its answer. |
curl -X POST "https://app.seomatic.ai/api/v1/tools/get_account_overview" \
-H "Authorization: Bearer $SEOMATIC_API_KEY"/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 answered. result is its output, usually a JSON string (parse it). A tool that refuses does NOT answer 200: it gets the matching 402/422/429/503 below, with its own output in result. |
400 | Invalid arguments (INVALID_ARGUMENTS; details says what) or a malformed Idempotency-Key (INVALID_IDEMPOTENCY_KEY). |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA); the plan does not include acting through the API (SCOPE_REVOKED_BY_PLAN); X-Seomatic-Client is n8n or make and the workspace has no paid plan or trial (AUTOMATION_NOT_ENTITLED); the free monthly question limit is reached (FREE_QUOTA_EXCEEDED; body carries keep_going_url and a question_pack payment link); the subscription is paused or its card was declined (BILLING_INACTIVE; body links the one step that restores it, never an upgrade); or the tool refused for credits (INSUFFICIENT_CREDITS, PAYMENT_REQUIRED; body carries the tool result); or the tool hit a plan limit (the code is the refusal code itself: PROMPT_LIMIT, CADENCE_LIMIT, MONITOR_LIMIT, PAGE_LIMIT_EXCEEDED, SEAT_LIMIT_EXCEEDED, WORKSPACE_LIMIT_EXCEEDED, PLANNER_DISABLED, AUTO_EXECUTE_DISABLED, AGENT_SKILLS_NOT_ENTITLED, PAGE_TEMPLATES_NOT_ENTITLED, HOSTED_PAGES_NOT_ENTITLED, AI_ATTRIBUTION_NOT_ENTITLED, ZAPIER_NOT_ENTITLED, BYO_KEYS_NOT_ENTITLED, INCREMENTALITY_NOT_ENTITLED, WEBHOOKS_NOT_ENTITLED; `result` holds the tool refusal). Body carries upgrade_url (and reason, for tool refusals) where an upgrade is the fix. |
403 | The plan allows it but the key creator's role in the workspace does not (FORBIDDEN_ROLE; e.g. a creator now a viewer calling an acting tool). No upgrade fixes it: an admin changes the role. |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
409 | A request with this Idempotency-Key is still running (IDEMPOTENCY_IN_PROGRESS; repeat after Retry-After to collect the result), or it ran and its answer was too large to keep (IDEMPOTENCY_RESULT_NOT_KEPT; it is not run again). |
413 | Request body over 256 KB (BODY_TOO_LARGE). Tool arguments are small JSON objects. |
422 | The tool refused: it needs a confirmation step first (NEEDS_CONFIRMATION), or it declined for another reason it states (TOOL_REFUSED); result holds its explanation. Or this Idempotency-Key was used for a different tool or arguments (IDEMPOTENCY_KEY_REUSED). |
429 | Rate limited: the per-key tool-call limit (Retry-After header set), or the tool refused for a rate cap (e.g. ARTICLE_FAILURE_CAP; body carries the tool result). |
502 | Tool execution failed (TOOL_FAILED) |
503 | Temporarily unavailable, on our side, not a limit: the upstream data provider or the credit check is down (PROVIDER_UNAVAILABLE; nothing was charged), or idempotency is unavailable and the tool was NOT run (IDEMPOTENCY_UNAVAILABLE). Retry shortly. |
504 | The tool is still running past the 60s response ceiling and was not stopped (TOOL_TIMEOUT). With an Idempotency-Key, repeat the request to collect its answer. |
curl -X POST "https://app.seomatic.ai/api/v1/tools/get_ad_campaigns" \
-H "Authorization: Bearer $SEOMATIC_API_KEY"/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 answered. result is its output, usually a JSON string (parse it). A tool that refuses does NOT answer 200: it gets the matching 402/422/429/503 below, with its own output in result. |
400 | Invalid arguments (INVALID_ARGUMENTS; details says what) or a malformed Idempotency-Key (INVALID_IDEMPOTENCY_KEY). |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA); the plan does not include acting through the API (SCOPE_REVOKED_BY_PLAN); X-Seomatic-Client is n8n or make and the workspace has no paid plan or trial (AUTOMATION_NOT_ENTITLED); the free monthly question limit is reached (FREE_QUOTA_EXCEEDED; body carries keep_going_url and a question_pack payment link); the subscription is paused or its card was declined (BILLING_INACTIVE; body links the one step that restores it, never an upgrade); or the tool refused for credits (INSUFFICIENT_CREDITS, PAYMENT_REQUIRED; body carries the tool result); or the tool hit a plan limit (the code is the refusal code itself: PROMPT_LIMIT, CADENCE_LIMIT, MONITOR_LIMIT, PAGE_LIMIT_EXCEEDED, SEAT_LIMIT_EXCEEDED, WORKSPACE_LIMIT_EXCEEDED, PLANNER_DISABLED, AUTO_EXECUTE_DISABLED, AGENT_SKILLS_NOT_ENTITLED, PAGE_TEMPLATES_NOT_ENTITLED, HOSTED_PAGES_NOT_ENTITLED, AI_ATTRIBUTION_NOT_ENTITLED, ZAPIER_NOT_ENTITLED, BYO_KEYS_NOT_ENTITLED, INCREMENTALITY_NOT_ENTITLED, WEBHOOKS_NOT_ENTITLED; `result` holds the tool refusal). Body carries upgrade_url (and reason, for tool refusals) where an upgrade is the fix. |
403 | The plan allows it but the key creator's role in the workspace does not (FORBIDDEN_ROLE; e.g. a creator now a viewer calling an acting tool). No upgrade fixes it: an admin changes the role. |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
409 | A request with this Idempotency-Key is still running (IDEMPOTENCY_IN_PROGRESS; repeat after Retry-After to collect the result), or it ran and its answer was too large to keep (IDEMPOTENCY_RESULT_NOT_KEPT; it is not run again). |
413 | Request body over 256 KB (BODY_TOO_LARGE). Tool arguments are small JSON objects. |
422 | The tool refused: it needs a confirmation step first (NEEDS_CONFIRMATION), or it declined for another reason it states (TOOL_REFUSED); result holds its explanation. Or this Idempotency-Key was used for a different tool or arguments (IDEMPOTENCY_KEY_REUSED). |
429 | Rate limited: the per-key tool-call limit (Retry-After header set), or the tool refused for a rate cap (e.g. ARTICLE_FAILURE_CAP; body carries the tool result). |
502 | Tool execution failed (TOOL_FAILED) |
503 | Temporarily unavailable, on our side, not a limit: the upstream data provider or the credit check is down (PROVIDER_UNAVAILABLE; nothing was charged), or idempotency is unavailable and the tool was NOT run (IDEMPOTENCY_UNAVAILABLE). Retry shortly. |
504 | The tool is still running past the 60s response ceiling and was not stopped (TOOL_TIMEOUT). With an Idempotency-Key, repeat the request to collect its answer. |
curl -X POST "https://app.seomatic.ai/api/v1/tools/get_search_terms" \
-H "Authorization: Bearer $SEOMATIC_API_KEY"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 answered. result is its output, usually a JSON string (parse it). A tool that refuses does NOT answer 200: it gets the matching 402/422/429/503 below, with its own output in result. |
400 | Invalid arguments (INVALID_ARGUMENTS; details says what) or a malformed Idempotency-Key (INVALID_IDEMPOTENCY_KEY). |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA); the plan does not include acting through the API (SCOPE_REVOKED_BY_PLAN); X-Seomatic-Client is n8n or make and the workspace has no paid plan or trial (AUTOMATION_NOT_ENTITLED); the free monthly question limit is reached (FREE_QUOTA_EXCEEDED; body carries keep_going_url and a question_pack payment link); the subscription is paused or its card was declined (BILLING_INACTIVE; body links the one step that restores it, never an upgrade); or the tool refused for credits (INSUFFICIENT_CREDITS, PAYMENT_REQUIRED; body carries the tool result); or the tool hit a plan limit (the code is the refusal code itself: PROMPT_LIMIT, CADENCE_LIMIT, MONITOR_LIMIT, PAGE_LIMIT_EXCEEDED, SEAT_LIMIT_EXCEEDED, WORKSPACE_LIMIT_EXCEEDED, PLANNER_DISABLED, AUTO_EXECUTE_DISABLED, AGENT_SKILLS_NOT_ENTITLED, PAGE_TEMPLATES_NOT_ENTITLED, HOSTED_PAGES_NOT_ENTITLED, AI_ATTRIBUTION_NOT_ENTITLED, ZAPIER_NOT_ENTITLED, BYO_KEYS_NOT_ENTITLED, INCREMENTALITY_NOT_ENTITLED, WEBHOOKS_NOT_ENTITLED; `result` holds the tool refusal). Body carries upgrade_url (and reason, for tool refusals) where an upgrade is the fix. |
403 | The plan allows it but the key creator's role in the workspace does not (FORBIDDEN_ROLE; e.g. a creator now a viewer calling an acting tool). No upgrade fixes it: an admin changes the role. |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
409 | A request with this Idempotency-Key is still running (IDEMPOTENCY_IN_PROGRESS; repeat after Retry-After to collect the result), or it ran and its answer was too large to keep (IDEMPOTENCY_RESULT_NOT_KEPT; it is not run again). |
413 | Request body over 256 KB (BODY_TOO_LARGE). Tool arguments are small JSON objects. |
422 | The tool refused: it needs a confirmation step first (NEEDS_CONFIRMATION), or it declined for another reason it states (TOOL_REFUSED); result holds its explanation. Or this Idempotency-Key was used for a different tool or arguments (IDEMPOTENCY_KEY_REUSED). |
429 | Rate limited: the per-key tool-call limit (Retry-After header set), or the tool refused for a rate cap (e.g. ARTICLE_FAILURE_CAP; body carries the tool result). |
502 | Tool execution failed (TOOL_FAILED) |
503 | Temporarily unavailable, on our side, not a limit: the upstream data provider or the credit check is down (PROVIDER_UNAVAILABLE; nothing was charged), or idempotency is unavailable and the tool was NOT run (IDEMPOTENCY_UNAVAILABLE). Retry shortly. |
504 | The tool is still running past the 60s response ceiling and was not stopped (TOOL_TIMEOUT). With an Idempotency-Key, repeat the request to collect its answer. |
curl -X POST "https://app.seomatic.ai/api/v1/tools/list_business_locations" \
-H "Authorization: Bearer $SEOMATIC_API_KEY"/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 answered. result is its output, usually a JSON string (parse it). A tool that refuses does NOT answer 200: it gets the matching 402/422/429/503 below, with its own output in result. |
400 | Invalid arguments (INVALID_ARGUMENTS; details says what) or a malformed Idempotency-Key (INVALID_IDEMPOTENCY_KEY). |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA); the plan does not include acting through the API (SCOPE_REVOKED_BY_PLAN); X-Seomatic-Client is n8n or make and the workspace has no paid plan or trial (AUTOMATION_NOT_ENTITLED); the free monthly question limit is reached (FREE_QUOTA_EXCEEDED; body carries keep_going_url and a question_pack payment link); the subscription is paused or its card was declined (BILLING_INACTIVE; body links the one step that restores it, never an upgrade); or the tool refused for credits (INSUFFICIENT_CREDITS, PAYMENT_REQUIRED; body carries the tool result); or the tool hit a plan limit (the code is the refusal code itself: PROMPT_LIMIT, CADENCE_LIMIT, MONITOR_LIMIT, PAGE_LIMIT_EXCEEDED, SEAT_LIMIT_EXCEEDED, WORKSPACE_LIMIT_EXCEEDED, PLANNER_DISABLED, AUTO_EXECUTE_DISABLED, AGENT_SKILLS_NOT_ENTITLED, PAGE_TEMPLATES_NOT_ENTITLED, HOSTED_PAGES_NOT_ENTITLED, AI_ATTRIBUTION_NOT_ENTITLED, ZAPIER_NOT_ENTITLED, BYO_KEYS_NOT_ENTITLED, INCREMENTALITY_NOT_ENTITLED, WEBHOOKS_NOT_ENTITLED; `result` holds the tool refusal). Body carries upgrade_url (and reason, for tool refusals) where an upgrade is the fix. |
403 | The plan allows it but the key creator's role in the workspace does not (FORBIDDEN_ROLE; e.g. a creator now a viewer calling an acting tool). No upgrade fixes it: an admin changes the role. |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
409 | A request with this Idempotency-Key is still running (IDEMPOTENCY_IN_PROGRESS; repeat after Retry-After to collect the result), or it ran and its answer was too large to keep (IDEMPOTENCY_RESULT_NOT_KEPT; it is not run again). |
413 | Request body over 256 KB (BODY_TOO_LARGE). Tool arguments are small JSON objects. |
422 | The tool refused: it needs a confirmation step first (NEEDS_CONFIRMATION), or it declined for another reason it states (TOOL_REFUSED); result holds its explanation. Or this Idempotency-Key was used for a different tool or arguments (IDEMPOTENCY_KEY_REUSED). |
429 | Rate limited: the per-key tool-call limit (Retry-After header set), or the tool refused for a rate cap (e.g. ARTICLE_FAILURE_CAP; body carries the tool result). |
502 | Tool execution failed (TOOL_FAILED) |
503 | Temporarily unavailable, on our side, not a limit: the upstream data provider or the credit check is down (PROVIDER_UNAVAILABLE; nothing was charged), or idempotency is unavailable and the tool was NOT run (IDEMPOTENCY_UNAVAILABLE). Retry shortly. |
504 | The tool is still running past the 60s response ceiling and was not stopped (TOOL_TIMEOUT). With an Idempotency-Key, repeat the request to collect its answer. |
curl -X POST "https://app.seomatic.ai/api/v1/tools/get_local_visibility" \
-H "Authorization: Bearer $SEOMATIC_API_KEY" \
-H "Content-Type: application/json" \
-d '{"keywords":[]}'/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 answered. result is its output, usually a JSON string (parse it). A tool that refuses does NOT answer 200: it gets the matching 402/422/429/503 below, with its own output in result. |
400 | Invalid arguments (INVALID_ARGUMENTS; details says what) or a malformed Idempotency-Key (INVALID_IDEMPOTENCY_KEY). |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA); the plan does not include acting through the API (SCOPE_REVOKED_BY_PLAN); X-Seomatic-Client is n8n or make and the workspace has no paid plan or trial (AUTOMATION_NOT_ENTITLED); the free monthly question limit is reached (FREE_QUOTA_EXCEEDED; body carries keep_going_url and a question_pack payment link); the subscription is paused or its card was declined (BILLING_INACTIVE; body links the one step that restores it, never an upgrade); or the tool refused for credits (INSUFFICIENT_CREDITS, PAYMENT_REQUIRED; body carries the tool result); or the tool hit a plan limit (the code is the refusal code itself: PROMPT_LIMIT, CADENCE_LIMIT, MONITOR_LIMIT, PAGE_LIMIT_EXCEEDED, SEAT_LIMIT_EXCEEDED, WORKSPACE_LIMIT_EXCEEDED, PLANNER_DISABLED, AUTO_EXECUTE_DISABLED, AGENT_SKILLS_NOT_ENTITLED, PAGE_TEMPLATES_NOT_ENTITLED, HOSTED_PAGES_NOT_ENTITLED, AI_ATTRIBUTION_NOT_ENTITLED, ZAPIER_NOT_ENTITLED, BYO_KEYS_NOT_ENTITLED, INCREMENTALITY_NOT_ENTITLED, WEBHOOKS_NOT_ENTITLED; `result` holds the tool refusal). Body carries upgrade_url (and reason, for tool refusals) where an upgrade is the fix. |
403 | The plan allows it but the key creator's role in the workspace does not (FORBIDDEN_ROLE; e.g. a creator now a viewer calling an acting tool). No upgrade fixes it: an admin changes the role. |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
409 | A request with this Idempotency-Key is still running (IDEMPOTENCY_IN_PROGRESS; repeat after Retry-After to collect the result), or it ran and its answer was too large to keep (IDEMPOTENCY_RESULT_NOT_KEPT; it is not run again). |
413 | Request body over 256 KB (BODY_TOO_LARGE). Tool arguments are small JSON objects. |
422 | The tool refused: it needs a confirmation step first (NEEDS_CONFIRMATION), or it declined for another reason it states (TOOL_REFUSED); result holds its explanation. Or this Idempotency-Key was used for a different tool or arguments (IDEMPOTENCY_KEY_REUSED). |
429 | Rate limited: the per-key tool-call limit (Retry-After header set), or the tool refused for a rate cap (e.g. ARTICLE_FAILURE_CAP; body carries the tool result). |
502 | Tool execution failed (TOOL_FAILED) |
503 | Temporarily unavailable, on our side, not a limit: the upstream data provider or the credit check is down (PROVIDER_UNAVAILABLE; nothing was charged), or idempotency is unavailable and the tool was NOT run (IDEMPOTENCY_UNAVAILABLE). Retry shortly. |
504 | The tool is still running past the 60s response ceiling and was not stopped (TOOL_TIMEOUT). With an Idempotency-Key, repeat the request to collect its answer. |
curl -X POST "https://app.seomatic.ai/api/v1/tools/get_business_reviews" \
-H "Authorization: Bearer $SEOMATIC_API_KEY" \
-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 answered. result is its output, usually a JSON string (parse it). A tool that refuses does NOT answer 200: it gets the matching 402/422/429/503 below, with its own output in result. |
400 | Invalid arguments (INVALID_ARGUMENTS; details says what) or a malformed Idempotency-Key (INVALID_IDEMPOTENCY_KEY). |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA); the plan does not include acting through the API (SCOPE_REVOKED_BY_PLAN); X-Seomatic-Client is n8n or make and the workspace has no paid plan or trial (AUTOMATION_NOT_ENTITLED); the free monthly question limit is reached (FREE_QUOTA_EXCEEDED; body carries keep_going_url and a question_pack payment link); the subscription is paused or its card was declined (BILLING_INACTIVE; body links the one step that restores it, never an upgrade); or the tool refused for credits (INSUFFICIENT_CREDITS, PAYMENT_REQUIRED; body carries the tool result); or the tool hit a plan limit (the code is the refusal code itself: PROMPT_LIMIT, CADENCE_LIMIT, MONITOR_LIMIT, PAGE_LIMIT_EXCEEDED, SEAT_LIMIT_EXCEEDED, WORKSPACE_LIMIT_EXCEEDED, PLANNER_DISABLED, AUTO_EXECUTE_DISABLED, AGENT_SKILLS_NOT_ENTITLED, PAGE_TEMPLATES_NOT_ENTITLED, HOSTED_PAGES_NOT_ENTITLED, AI_ATTRIBUTION_NOT_ENTITLED, ZAPIER_NOT_ENTITLED, BYO_KEYS_NOT_ENTITLED, INCREMENTALITY_NOT_ENTITLED, WEBHOOKS_NOT_ENTITLED; `result` holds the tool refusal). Body carries upgrade_url (and reason, for tool refusals) where an upgrade is the fix. |
403 | The plan allows it but the key creator's role in the workspace does not (FORBIDDEN_ROLE; e.g. a creator now a viewer calling an acting tool). No upgrade fixes it: an admin changes the role. |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
409 | A request with this Idempotency-Key is still running (IDEMPOTENCY_IN_PROGRESS; repeat after Retry-After to collect the result), or it ran and its answer was too large to keep (IDEMPOTENCY_RESULT_NOT_KEPT; it is not run again). |
413 | Request body over 256 KB (BODY_TOO_LARGE). Tool arguments are small JSON objects. |
422 | The tool refused: it needs a confirmation step first (NEEDS_CONFIRMATION), or it declined for another reason it states (TOOL_REFUSED); result holds its explanation. Or this Idempotency-Key was used for a different tool or arguments (IDEMPOTENCY_KEY_REUSED). |
429 | Rate limited: the per-key tool-call limit (Retry-After header set), or the tool refused for a rate cap (e.g. ARTICLE_FAILURE_CAP; body carries the tool result). |
502 | Tool execution failed (TOOL_FAILED) |
503 | Temporarily unavailable, on our side, not a limit: the upstream data provider or the credit check is down (PROVIDER_UNAVAILABLE; nothing was charged), or idempotency is unavailable and the tool was NOT run (IDEMPOTENCY_UNAVAILABLE). Retry shortly. |
504 | The tool is still running past the 60s response ceiling and was not stopped (TOOL_TIMEOUT). With an Idempotency-Key, repeat the request to collect its answer. |
curl -X POST "https://app.seomatic.ai/api/v1/tools/get_seo_snapshot" \
-H "Authorization: Bearer $SEOMATIC_API_KEY"/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 answered. result is its output, usually a JSON string (parse it). A tool that refuses does NOT answer 200: it gets the matching 402/422/429/503 below, with its own output in result. |
400 | Invalid arguments (INVALID_ARGUMENTS; details says what) or a malformed Idempotency-Key (INVALID_IDEMPOTENCY_KEY). |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA); the plan does not include acting through the API (SCOPE_REVOKED_BY_PLAN); X-Seomatic-Client is n8n or make and the workspace has no paid plan or trial (AUTOMATION_NOT_ENTITLED); the free monthly question limit is reached (FREE_QUOTA_EXCEEDED; body carries keep_going_url and a question_pack payment link); the subscription is paused or its card was declined (BILLING_INACTIVE; body links the one step that restores it, never an upgrade); or the tool refused for credits (INSUFFICIENT_CREDITS, PAYMENT_REQUIRED; body carries the tool result); or the tool hit a plan limit (the code is the refusal code itself: PROMPT_LIMIT, CADENCE_LIMIT, MONITOR_LIMIT, PAGE_LIMIT_EXCEEDED, SEAT_LIMIT_EXCEEDED, WORKSPACE_LIMIT_EXCEEDED, PLANNER_DISABLED, AUTO_EXECUTE_DISABLED, AGENT_SKILLS_NOT_ENTITLED, PAGE_TEMPLATES_NOT_ENTITLED, HOSTED_PAGES_NOT_ENTITLED, AI_ATTRIBUTION_NOT_ENTITLED, ZAPIER_NOT_ENTITLED, BYO_KEYS_NOT_ENTITLED, INCREMENTALITY_NOT_ENTITLED, WEBHOOKS_NOT_ENTITLED; `result` holds the tool refusal). Body carries upgrade_url (and reason, for tool refusals) where an upgrade is the fix. |
403 | The plan allows it but the key creator's role in the workspace does not (FORBIDDEN_ROLE; e.g. a creator now a viewer calling an acting tool). No upgrade fixes it: an admin changes the role. |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
409 | A request with this Idempotency-Key is still running (IDEMPOTENCY_IN_PROGRESS; repeat after Retry-After to collect the result), or it ran and its answer was too large to keep (IDEMPOTENCY_RESULT_NOT_KEPT; it is not run again). |
413 | Request body over 256 KB (BODY_TOO_LARGE). Tool arguments are small JSON objects. |
422 | The tool refused: it needs a confirmation step first (NEEDS_CONFIRMATION), or it declined for another reason it states (TOOL_REFUSED); result holds its explanation. Or this Idempotency-Key was used for a different tool or arguments (IDEMPOTENCY_KEY_REUSED). |
429 | Rate limited: the per-key tool-call limit (Retry-After header set), or the tool refused for a rate cap (e.g. ARTICLE_FAILURE_CAP; body carries the tool result). |
502 | Tool execution failed (TOOL_FAILED) |
503 | Temporarily unavailable, on our side, not a limit: the upstream data provider or the credit check is down (PROVIDER_UNAVAILABLE; nothing was charged), or idempotency is unavailable and the tool was NOT run (IDEMPOTENCY_UNAVAILABLE). Retry shortly. |
504 | The tool is still running past the 60s response ceiling and was not stopped (TOOL_TIMEOUT). With an Idempotency-Key, repeat the request to collect its answer. |
curl -X POST "https://app.seomatic.ai/api/v1/tools/get_seo_strategy" \
-H "Authorization: Bearer $SEOMATIC_API_KEY"/tools/get_target_termsreadThe searches this business says bring it customers, each with the page that should show for it and a priority (high, medium, low). The agents plan around them: when Google shows a different page for…
| Status | Description |
|---|---|
200 | { tool, result }: the tool answered. result is its output, usually a JSON string (parse it). A tool that refuses does NOT answer 200: it gets the matching 402/422/429/503 below, with its own output in result. |
400 | Invalid arguments (INVALID_ARGUMENTS; details says what) or a malformed Idempotency-Key (INVALID_IDEMPOTENCY_KEY). |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA); the plan does not include acting through the API (SCOPE_REVOKED_BY_PLAN); X-Seomatic-Client is n8n or make and the workspace has no paid plan or trial (AUTOMATION_NOT_ENTITLED); the free monthly question limit is reached (FREE_QUOTA_EXCEEDED; body carries keep_going_url and a question_pack payment link); the subscription is paused or its card was declined (BILLING_INACTIVE; body links the one step that restores it, never an upgrade); or the tool refused for credits (INSUFFICIENT_CREDITS, PAYMENT_REQUIRED; body carries the tool result); or the tool hit a plan limit (the code is the refusal code itself: PROMPT_LIMIT, CADENCE_LIMIT, MONITOR_LIMIT, PAGE_LIMIT_EXCEEDED, SEAT_LIMIT_EXCEEDED, WORKSPACE_LIMIT_EXCEEDED, PLANNER_DISABLED, AUTO_EXECUTE_DISABLED, AGENT_SKILLS_NOT_ENTITLED, PAGE_TEMPLATES_NOT_ENTITLED, HOSTED_PAGES_NOT_ENTITLED, AI_ATTRIBUTION_NOT_ENTITLED, ZAPIER_NOT_ENTITLED, BYO_KEYS_NOT_ENTITLED, INCREMENTALITY_NOT_ENTITLED, WEBHOOKS_NOT_ENTITLED; `result` holds the tool refusal). Body carries upgrade_url (and reason, for tool refusals) where an upgrade is the fix. |
403 | The plan allows it but the key creator's role in the workspace does not (FORBIDDEN_ROLE; e.g. a creator now a viewer calling an acting tool). No upgrade fixes it: an admin changes the role. |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
409 | A request with this Idempotency-Key is still running (IDEMPOTENCY_IN_PROGRESS; repeat after Retry-After to collect the result), or it ran and its answer was too large to keep (IDEMPOTENCY_RESULT_NOT_KEPT; it is not run again). |
413 | Request body over 256 KB (BODY_TOO_LARGE). Tool arguments are small JSON objects. |
422 | The tool refused: it needs a confirmation step first (NEEDS_CONFIRMATION), or it declined for another reason it states (TOOL_REFUSED); result holds its explanation. Or this Idempotency-Key was used for a different tool or arguments (IDEMPOTENCY_KEY_REUSED). |
429 | Rate limited: the per-key tool-call limit (Retry-After header set), or the tool refused for a rate cap (e.g. ARTICLE_FAILURE_CAP; body carries the tool result). |
502 | Tool execution failed (TOOL_FAILED) |
503 | Temporarily unavailable, on our side, not a limit: the upstream data provider or the credit check is down (PROVIDER_UNAVAILABLE; nothing was charged), or idempotency is unavailable and the tool was NOT run (IDEMPOTENCY_UNAVAILABLE). Retry shortly. |
504 | The tool is still running past the 60s response ceiling and was not stopped (TOOL_TIMEOUT). With an Idempotency-Key, repeat the request to collect its answer. |
curl -X POST "https://app.seomatic.ai/api/v1/tools/get_target_terms" \
-H "Authorization: Bearer $SEOMATIC_API_KEY"/tools/set_target_termsreadSave the searches the user says bring them business: add or update terms (each with the full URL of the page on their own site that should show for it, and a priority), or remove terms. Call only wit…
| Name | Type | Required | Description |
|---|---|---|---|
add | object[] | no | Terms to add or update (same term = update) |
remove | string[] | no | Terms to stop tracking |
| Status | Description |
|---|---|
200 | { tool, result }: the tool answered. result is its output, usually a JSON string (parse it). A tool that refuses does NOT answer 200: it gets the matching 402/422/429/503 below, with its own output in result. |
400 | Invalid arguments (INVALID_ARGUMENTS; details says what) or a malformed Idempotency-Key (INVALID_IDEMPOTENCY_KEY). |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA); the plan does not include acting through the API (SCOPE_REVOKED_BY_PLAN); X-Seomatic-Client is n8n or make and the workspace has no paid plan or trial (AUTOMATION_NOT_ENTITLED); the free monthly question limit is reached (FREE_QUOTA_EXCEEDED; body carries keep_going_url and a question_pack payment link); the subscription is paused or its card was declined (BILLING_INACTIVE; body links the one step that restores it, never an upgrade); or the tool refused for credits (INSUFFICIENT_CREDITS, PAYMENT_REQUIRED; body carries the tool result); or the tool hit a plan limit (the code is the refusal code itself: PROMPT_LIMIT, CADENCE_LIMIT, MONITOR_LIMIT, PAGE_LIMIT_EXCEEDED, SEAT_LIMIT_EXCEEDED, WORKSPACE_LIMIT_EXCEEDED, PLANNER_DISABLED, AUTO_EXECUTE_DISABLED, AGENT_SKILLS_NOT_ENTITLED, PAGE_TEMPLATES_NOT_ENTITLED, HOSTED_PAGES_NOT_ENTITLED, AI_ATTRIBUTION_NOT_ENTITLED, ZAPIER_NOT_ENTITLED, BYO_KEYS_NOT_ENTITLED, INCREMENTALITY_NOT_ENTITLED, WEBHOOKS_NOT_ENTITLED; `result` holds the tool refusal). Body carries upgrade_url (and reason, for tool refusals) where an upgrade is the fix. |
403 | The plan allows it but the key creator's role in the workspace does not (FORBIDDEN_ROLE; e.g. a creator now a viewer calling an acting tool). No upgrade fixes it: an admin changes the role. |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
409 | A request with this Idempotency-Key is still running (IDEMPOTENCY_IN_PROGRESS; repeat after Retry-After to collect the result), or it ran and its answer was too large to keep (IDEMPOTENCY_RESULT_NOT_KEPT; it is not run again). |
413 | Request body over 256 KB (BODY_TOO_LARGE). Tool arguments are small JSON objects. |
422 | The tool refused: it needs a confirmation step first (NEEDS_CONFIRMATION), or it declined for another reason it states (TOOL_REFUSED); result holds its explanation. Or this Idempotency-Key was used for a different tool or arguments (IDEMPOTENCY_KEY_REUSED). |
429 | Rate limited: the per-key tool-call limit (Retry-After header set), or the tool refused for a rate cap (e.g. ARTICLE_FAILURE_CAP; body carries the tool result). |
502 | Tool execution failed (TOOL_FAILED) |
503 | Temporarily unavailable, on our side, not a limit: the upstream data provider or the credit check is down (PROVIDER_UNAVAILABLE; nothing was charged), or idempotency is unavailable and the tool was NOT run (IDEMPOTENCY_UNAVAILABLE). Retry shortly. |
504 | The tool is still running past the 60s response ceiling and was not stopped (TOOL_TIMEOUT). With an Idempotency-Key, repeat the request to collect its answer. |
curl -X POST "https://app.seomatic.ai/api/v1/tools/set_target_terms" \
-H "Authorization: Bearer $SEOMATIC_API_KEY"/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 | fact_finder | yes | Which cached signal to read |
| Status | Description |
|---|---|
200 | { tool, result }: the tool answered. result is its output, usually a JSON string (parse it). A tool that refuses does NOT answer 200: it gets the matching 402/422/429/503 below, with its own output in result. |
400 | Invalid arguments (INVALID_ARGUMENTS; details says what) or a malformed Idempotency-Key (INVALID_IDEMPOTENCY_KEY). |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA); the plan does not include acting through the API (SCOPE_REVOKED_BY_PLAN); X-Seomatic-Client is n8n or make and the workspace has no paid plan or trial (AUTOMATION_NOT_ENTITLED); the free monthly question limit is reached (FREE_QUOTA_EXCEEDED; body carries keep_going_url and a question_pack payment link); the subscription is paused or its card was declined (BILLING_INACTIVE; body links the one step that restores it, never an upgrade); or the tool refused for credits (INSUFFICIENT_CREDITS, PAYMENT_REQUIRED; body carries the tool result); or the tool hit a plan limit (the code is the refusal code itself: PROMPT_LIMIT, CADENCE_LIMIT, MONITOR_LIMIT, PAGE_LIMIT_EXCEEDED, SEAT_LIMIT_EXCEEDED, WORKSPACE_LIMIT_EXCEEDED, PLANNER_DISABLED, AUTO_EXECUTE_DISABLED, AGENT_SKILLS_NOT_ENTITLED, PAGE_TEMPLATES_NOT_ENTITLED, HOSTED_PAGES_NOT_ENTITLED, AI_ATTRIBUTION_NOT_ENTITLED, ZAPIER_NOT_ENTITLED, BYO_KEYS_NOT_ENTITLED, INCREMENTALITY_NOT_ENTITLED, WEBHOOKS_NOT_ENTITLED; `result` holds the tool refusal). Body carries upgrade_url (and reason, for tool refusals) where an upgrade is the fix. |
403 | The plan allows it but the key creator's role in the workspace does not (FORBIDDEN_ROLE; e.g. a creator now a viewer calling an acting tool). No upgrade fixes it: an admin changes the role. |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
409 | A request with this Idempotency-Key is still running (IDEMPOTENCY_IN_PROGRESS; repeat after Retry-After to collect the result), or it ran and its answer was too large to keep (IDEMPOTENCY_RESULT_NOT_KEPT; it is not run again). |
413 | Request body over 256 KB (BODY_TOO_LARGE). Tool arguments are small JSON objects. |
422 | The tool refused: it needs a confirmation step first (NEEDS_CONFIRMATION), or it declined for another reason it states (TOOL_REFUSED); result holds its explanation. Or this Idempotency-Key was used for a different tool or arguments (IDEMPOTENCY_KEY_REUSED). |
429 | Rate limited: the per-key tool-call limit (Retry-After header set), or the tool refused for a rate cap (e.g. ARTICLE_FAILURE_CAP; body carries the tool result). |
502 | Tool execution failed (TOOL_FAILED) |
503 | Temporarily unavailable, on our side, not a limit: the upstream data provider or the credit check is down (PROVIDER_UNAVAILABLE; nothing was charged), or idempotency is unavailable and the tool was NOT run (IDEMPOTENCY_UNAVAILABLE). Retry shortly. |
504 | The tool is still running past the 60s response ceiling and was not stopped (TOOL_TIMEOUT). With an Idempotency-Key, repeat the request to collect its answer. |
curl -X POST "https://app.seomatic.ai/api/v1/tools/get_seo_signal" \
-H "Authorization: Bearer $SEOMATIC_API_KEY" \
-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 answered. result is its output, usually a JSON string (parse it). A tool that refuses does NOT answer 200: it gets the matching 402/422/429/503 below, with its own output in result. |
400 | Invalid arguments (INVALID_ARGUMENTS; details says what) or a malformed Idempotency-Key (INVALID_IDEMPOTENCY_KEY). |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA); the plan does not include acting through the API (SCOPE_REVOKED_BY_PLAN); X-Seomatic-Client is n8n or make and the workspace has no paid plan or trial (AUTOMATION_NOT_ENTITLED); the free monthly question limit is reached (FREE_QUOTA_EXCEEDED; body carries keep_going_url and a question_pack payment link); the subscription is paused or its card was declined (BILLING_INACTIVE; body links the one step that restores it, never an upgrade); or the tool refused for credits (INSUFFICIENT_CREDITS, PAYMENT_REQUIRED; body carries the tool result); or the tool hit a plan limit (the code is the refusal code itself: PROMPT_LIMIT, CADENCE_LIMIT, MONITOR_LIMIT, PAGE_LIMIT_EXCEEDED, SEAT_LIMIT_EXCEEDED, WORKSPACE_LIMIT_EXCEEDED, PLANNER_DISABLED, AUTO_EXECUTE_DISABLED, AGENT_SKILLS_NOT_ENTITLED, PAGE_TEMPLATES_NOT_ENTITLED, HOSTED_PAGES_NOT_ENTITLED, AI_ATTRIBUTION_NOT_ENTITLED, ZAPIER_NOT_ENTITLED, BYO_KEYS_NOT_ENTITLED, INCREMENTALITY_NOT_ENTITLED, WEBHOOKS_NOT_ENTITLED; `result` holds the tool refusal). Body carries upgrade_url (and reason, for tool refusals) where an upgrade is the fix. |
403 | The plan allows it but the key creator's role in the workspace does not (FORBIDDEN_ROLE; e.g. a creator now a viewer calling an acting tool). No upgrade fixes it: an admin changes the role. |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
409 | A request with this Idempotency-Key is still running (IDEMPOTENCY_IN_PROGRESS; repeat after Retry-After to collect the result), or it ran and its answer was too large to keep (IDEMPOTENCY_RESULT_NOT_KEPT; it is not run again). |
413 | Request body over 256 KB (BODY_TOO_LARGE). Tool arguments are small JSON objects. |
422 | The tool refused: it needs a confirmation step first (NEEDS_CONFIRMATION), or it declined for another reason it states (TOOL_REFUSED); result holds its explanation. Or this Idempotency-Key was used for a different tool or arguments (IDEMPOTENCY_KEY_REUSED). |
429 | Rate limited: the per-key tool-call limit (Retry-After header set), or the tool refused for a rate cap (e.g. ARTICLE_FAILURE_CAP; body carries the tool result). |
502 | Tool execution failed (TOOL_FAILED) |
503 | Temporarily unavailable, on our side, not a limit: the upstream data provider or the credit check is down (PROVIDER_UNAVAILABLE; nothing was charged), or idempotency is unavailable and the tool was NOT run (IDEMPOTENCY_UNAVAILABLE). Retry shortly. |
504 | The tool is still running past the 60s response ceiling and was not stopped (TOOL_TIMEOUT). With an Idempotency-Key, repeat the request to collect its answer. |
curl -X POST "https://app.seomatic.ai/api/v1/tools/get_content_scores" \
-H "Authorization: Bearer $SEOMATIC_API_KEY"/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 answered. result is its output, usually a JSON string (parse it). A tool that refuses does NOT answer 200: it gets the matching 402/422/429/503 below, with its own output in result. |
400 | Invalid arguments (INVALID_ARGUMENTS; details says what) or a malformed Idempotency-Key (INVALID_IDEMPOTENCY_KEY). |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA); the plan does not include acting through the API (SCOPE_REVOKED_BY_PLAN); X-Seomatic-Client is n8n or make and the workspace has no paid plan or trial (AUTOMATION_NOT_ENTITLED); the free monthly question limit is reached (FREE_QUOTA_EXCEEDED; body carries keep_going_url and a question_pack payment link); the subscription is paused or its card was declined (BILLING_INACTIVE; body links the one step that restores it, never an upgrade); or the tool refused for credits (INSUFFICIENT_CREDITS, PAYMENT_REQUIRED; body carries the tool result); or the tool hit a plan limit (the code is the refusal code itself: PROMPT_LIMIT, CADENCE_LIMIT, MONITOR_LIMIT, PAGE_LIMIT_EXCEEDED, SEAT_LIMIT_EXCEEDED, WORKSPACE_LIMIT_EXCEEDED, PLANNER_DISABLED, AUTO_EXECUTE_DISABLED, AGENT_SKILLS_NOT_ENTITLED, PAGE_TEMPLATES_NOT_ENTITLED, HOSTED_PAGES_NOT_ENTITLED, AI_ATTRIBUTION_NOT_ENTITLED, ZAPIER_NOT_ENTITLED, BYO_KEYS_NOT_ENTITLED, INCREMENTALITY_NOT_ENTITLED, WEBHOOKS_NOT_ENTITLED; `result` holds the tool refusal). Body carries upgrade_url (and reason, for tool refusals) where an upgrade is the fix. |
403 | The plan allows it but the key creator's role in the workspace does not (FORBIDDEN_ROLE; e.g. a creator now a viewer calling an acting tool). No upgrade fixes it: an admin changes the role. |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
409 | A request with this Idempotency-Key is still running (IDEMPOTENCY_IN_PROGRESS; repeat after Retry-After to collect the result), or it ran and its answer was too large to keep (IDEMPOTENCY_RESULT_NOT_KEPT; it is not run again). |
413 | Request body over 256 KB (BODY_TOO_LARGE). Tool arguments are small JSON objects. |
422 | The tool refused: it needs a confirmation step first (NEEDS_CONFIRMATION), or it declined for another reason it states (TOOL_REFUSED); result holds its explanation. Or this Idempotency-Key was used for a different tool or arguments (IDEMPOTENCY_KEY_REUSED). |
429 | Rate limited: the per-key tool-call limit (Retry-After header set), or the tool refused for a rate cap (e.g. ARTICLE_FAILURE_CAP; body carries the tool result). |
502 | Tool execution failed (TOOL_FAILED) |
503 | Temporarily unavailable, on our side, not a limit: the upstream data provider or the credit check is down (PROVIDER_UNAVAILABLE; nothing was charged), or idempotency is unavailable and the tool was NOT run (IDEMPOTENCY_UNAVAILABLE). Retry shortly. |
504 | The tool is still running past the 60s response ceiling and was not stopped (TOOL_TIMEOUT). With an Idempotency-Key, repeat the request to collect its answer. |
curl -X POST "https://app.seomatic.ai/api/v1/tools/list_seo_tasks" \
-H "Authorization: Bearer $SEOMATIC_API_KEY" \
-H "Idempotency-Key: $(uuidgen)"/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 answered. result is its output, usually a JSON string (parse it). A tool that refuses does NOT answer 200: it gets the matching 402/422/429/503 below, with its own output in result. |
400 | Invalid arguments (INVALID_ARGUMENTS; details says what) or a malformed Idempotency-Key (INVALID_IDEMPOTENCY_KEY). |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA); the plan does not include acting through the API (SCOPE_REVOKED_BY_PLAN); X-Seomatic-Client is n8n or make and the workspace has no paid plan or trial (AUTOMATION_NOT_ENTITLED); the free monthly question limit is reached (FREE_QUOTA_EXCEEDED; body carries keep_going_url and a question_pack payment link); the subscription is paused or its card was declined (BILLING_INACTIVE; body links the one step that restores it, never an upgrade); or the tool refused for credits (INSUFFICIENT_CREDITS, PAYMENT_REQUIRED; body carries the tool result); or the tool hit a plan limit (the code is the refusal code itself: PROMPT_LIMIT, CADENCE_LIMIT, MONITOR_LIMIT, PAGE_LIMIT_EXCEEDED, SEAT_LIMIT_EXCEEDED, WORKSPACE_LIMIT_EXCEEDED, PLANNER_DISABLED, AUTO_EXECUTE_DISABLED, AGENT_SKILLS_NOT_ENTITLED, PAGE_TEMPLATES_NOT_ENTITLED, HOSTED_PAGES_NOT_ENTITLED, AI_ATTRIBUTION_NOT_ENTITLED, ZAPIER_NOT_ENTITLED, BYO_KEYS_NOT_ENTITLED, INCREMENTALITY_NOT_ENTITLED, WEBHOOKS_NOT_ENTITLED; `result` holds the tool refusal). Body carries upgrade_url (and reason, for tool refusals) where an upgrade is the fix. |
403 | The plan allows it but the key creator's role in the workspace does not (FORBIDDEN_ROLE; e.g. a creator now a viewer calling an acting tool). No upgrade fixes it: an admin changes the role. |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
409 | A request with this Idempotency-Key is still running (IDEMPOTENCY_IN_PROGRESS; repeat after Retry-After to collect the result), or it ran and its answer was too large to keep (IDEMPOTENCY_RESULT_NOT_KEPT; it is not run again). |
413 | Request body over 256 KB (BODY_TOO_LARGE). Tool arguments are small JSON objects. |
422 | The tool refused: it needs a confirmation step first (NEEDS_CONFIRMATION), or it declined for another reason it states (TOOL_REFUSED); result holds its explanation. Or this Idempotency-Key was used for a different tool or arguments (IDEMPOTENCY_KEY_REUSED). |
429 | Rate limited: the per-key tool-call limit (Retry-After header set), or the tool refused for a rate cap (e.g. ARTICLE_FAILURE_CAP; body carries the tool result). |
502 | Tool execution failed (TOOL_FAILED) |
503 | Temporarily unavailable, on our side, not a limit: the upstream data provider or the credit check is down (PROVIDER_UNAVAILABLE; nothing was charged), or idempotency is unavailable and the tool was NOT run (IDEMPOTENCY_UNAVAILABLE). Retry shortly. |
504 | The tool is still running past the 60s response ceiling and was not stopped (TOOL_TIMEOUT). With an Idempotency-Key, repeat the request to collect its answer. |
curl -X POST "https://app.seomatic.ai/api/v1/tools/get_seo_task" \
-H "Authorization: Bearer $SEOMATIC_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-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 answered. result is its output, usually a JSON string (parse it). A tool that refuses does NOT answer 200: it gets the matching 402/422/429/503 below, with its own output in result. |
400 | Invalid arguments (INVALID_ARGUMENTS; details says what) or a malformed Idempotency-Key (INVALID_IDEMPOTENCY_KEY). |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA); the plan does not include acting through the API (SCOPE_REVOKED_BY_PLAN); X-Seomatic-Client is n8n or make and the workspace has no paid plan or trial (AUTOMATION_NOT_ENTITLED); the free monthly question limit is reached (FREE_QUOTA_EXCEEDED; body carries keep_going_url and a question_pack payment link); the subscription is paused or its card was declined (BILLING_INACTIVE; body links the one step that restores it, never an upgrade); or the tool refused for credits (INSUFFICIENT_CREDITS, PAYMENT_REQUIRED; body carries the tool result); or the tool hit a plan limit (the code is the refusal code itself: PROMPT_LIMIT, CADENCE_LIMIT, MONITOR_LIMIT, PAGE_LIMIT_EXCEEDED, SEAT_LIMIT_EXCEEDED, WORKSPACE_LIMIT_EXCEEDED, PLANNER_DISABLED, AUTO_EXECUTE_DISABLED, AGENT_SKILLS_NOT_ENTITLED, PAGE_TEMPLATES_NOT_ENTITLED, HOSTED_PAGES_NOT_ENTITLED, AI_ATTRIBUTION_NOT_ENTITLED, ZAPIER_NOT_ENTITLED, BYO_KEYS_NOT_ENTITLED, INCREMENTALITY_NOT_ENTITLED, WEBHOOKS_NOT_ENTITLED; `result` holds the tool refusal). Body carries upgrade_url (and reason, for tool refusals) where an upgrade is the fix. |
403 | The plan allows it but the key creator's role in the workspace does not (FORBIDDEN_ROLE; e.g. a creator now a viewer calling an acting tool). No upgrade fixes it: an admin changes the role. |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
409 | A request with this Idempotency-Key is still running (IDEMPOTENCY_IN_PROGRESS; repeat after Retry-After to collect the result), or it ran and its answer was too large to keep (IDEMPOTENCY_RESULT_NOT_KEPT; it is not run again). |
413 | Request body over 256 KB (BODY_TOO_LARGE). Tool arguments are small JSON objects. |
422 | The tool refused: it needs a confirmation step first (NEEDS_CONFIRMATION), or it declined for another reason it states (TOOL_REFUSED); result holds its explanation. Or this Idempotency-Key was used for a different tool or arguments (IDEMPOTENCY_KEY_REUSED). |
429 | Rate limited: the per-key tool-call limit (Retry-After header set), or the tool refused for a rate cap (e.g. ARTICLE_FAILURE_CAP; body carries the tool result). |
502 | Tool execution failed (TOOL_FAILED) |
503 | Temporarily unavailable, on our side, not a limit: the upstream data provider or the credit check is down (PROVIDER_UNAVAILABLE; nothing was charged), or idempotency is unavailable and the tool was NOT run (IDEMPOTENCY_UNAVAILABLE). Retry shortly. |
504 | The tool is still running past the 60s response ceiling and was not stopped (TOOL_TIMEOUT). With an Idempotency-Key, repeat the request to collect its answer. |
curl -X POST "https://app.seomatic.ai/api/v1/tools/load_skill" \
-H "Authorization: Bearer $SEOMATIC_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-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 answered. result is its output, usually a JSON string (parse it). A tool that refuses does NOT answer 200: it gets the matching 402/422/429/503 below, with its own output in result. |
400 | Invalid arguments (INVALID_ARGUMENTS; details says what) or a malformed Idempotency-Key (INVALID_IDEMPOTENCY_KEY). |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA); the plan does not include acting through the API (SCOPE_REVOKED_BY_PLAN); X-Seomatic-Client is n8n or make and the workspace has no paid plan or trial (AUTOMATION_NOT_ENTITLED); the free monthly question limit is reached (FREE_QUOTA_EXCEEDED; body carries keep_going_url and a question_pack payment link); the subscription is paused or its card was declined (BILLING_INACTIVE; body links the one step that restores it, never an upgrade); or the tool refused for credits (INSUFFICIENT_CREDITS, PAYMENT_REQUIRED; body carries the tool result); or the tool hit a plan limit (the code is the refusal code itself: PROMPT_LIMIT, CADENCE_LIMIT, MONITOR_LIMIT, PAGE_LIMIT_EXCEEDED, SEAT_LIMIT_EXCEEDED, WORKSPACE_LIMIT_EXCEEDED, PLANNER_DISABLED, AUTO_EXECUTE_DISABLED, AGENT_SKILLS_NOT_ENTITLED, PAGE_TEMPLATES_NOT_ENTITLED, HOSTED_PAGES_NOT_ENTITLED, AI_ATTRIBUTION_NOT_ENTITLED, ZAPIER_NOT_ENTITLED, BYO_KEYS_NOT_ENTITLED, INCREMENTALITY_NOT_ENTITLED, WEBHOOKS_NOT_ENTITLED; `result` holds the tool refusal). Body carries upgrade_url (and reason, for tool refusals) where an upgrade is the fix. |
403 | The plan allows it but the key creator's role in the workspace does not (FORBIDDEN_ROLE; e.g. a creator now a viewer calling an acting tool). No upgrade fixes it: an admin changes the role. |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
409 | A request with this Idempotency-Key is still running (IDEMPOTENCY_IN_PROGRESS; repeat after Retry-After to collect the result), or it ran and its answer was too large to keep (IDEMPOTENCY_RESULT_NOT_KEPT; it is not run again). |
413 | Request body over 256 KB (BODY_TOO_LARGE). Tool arguments are small JSON objects. |
422 | The tool refused: it needs a confirmation step first (NEEDS_CONFIRMATION), or it declined for another reason it states (TOOL_REFUSED); result holds its explanation. Or this Idempotency-Key was used for a different tool or arguments (IDEMPOTENCY_KEY_REUSED). |
429 | Rate limited: the per-key tool-call limit (Retry-After header set), or the tool refused for a rate cap (e.g. ARTICLE_FAILURE_CAP; body carries the tool result). |
502 | Tool execution failed (TOOL_FAILED) |
503 | Temporarily unavailable, on our side, not a limit: the upstream data provider or the credit check is down (PROVIDER_UNAVAILABLE; nothing was charged), or idempotency is unavailable and the tool was NOT run (IDEMPOTENCY_UNAVAILABLE). Retry shortly. |
504 | The tool is still running past the 60s response ceiling and was not stopped (TOOL_TIMEOUT). With an Idempotency-Key, repeat the request to collect its answer. |
curl -X POST "https://app.seomatic.ai/api/v1/tools/create_seo_tasks" \
-H "Authorization: Bearer $SEOMATIC_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"tasks":[]}'/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 answered. result is its output, usually a JSON string (parse it). A tool that refuses does NOT answer 200: it gets the matching 402/422/429/503 below, with its own output in result. |
400 | Invalid arguments (INVALID_ARGUMENTS; details says what) or a malformed Idempotency-Key (INVALID_IDEMPOTENCY_KEY). |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA); the plan does not include acting through the API (SCOPE_REVOKED_BY_PLAN); X-Seomatic-Client is n8n or make and the workspace has no paid plan or trial (AUTOMATION_NOT_ENTITLED); the free monthly question limit is reached (FREE_QUOTA_EXCEEDED; body carries keep_going_url and a question_pack payment link); the subscription is paused or its card was declined (BILLING_INACTIVE; body links the one step that restores it, never an upgrade); or the tool refused for credits (INSUFFICIENT_CREDITS, PAYMENT_REQUIRED; body carries the tool result); or the tool hit a plan limit (the code is the refusal code itself: PROMPT_LIMIT, CADENCE_LIMIT, MONITOR_LIMIT, PAGE_LIMIT_EXCEEDED, SEAT_LIMIT_EXCEEDED, WORKSPACE_LIMIT_EXCEEDED, PLANNER_DISABLED, AUTO_EXECUTE_DISABLED, AGENT_SKILLS_NOT_ENTITLED, PAGE_TEMPLATES_NOT_ENTITLED, HOSTED_PAGES_NOT_ENTITLED, AI_ATTRIBUTION_NOT_ENTITLED, ZAPIER_NOT_ENTITLED, BYO_KEYS_NOT_ENTITLED, INCREMENTALITY_NOT_ENTITLED, WEBHOOKS_NOT_ENTITLED; `result` holds the tool refusal). Body carries upgrade_url (and reason, for tool refusals) where an upgrade is the fix. |
403 | The plan allows it but the key creator's role in the workspace does not (FORBIDDEN_ROLE; e.g. a creator now a viewer calling an acting tool). No upgrade fixes it: an admin changes the role. |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
409 | A request with this Idempotency-Key is still running (IDEMPOTENCY_IN_PROGRESS; repeat after Retry-After to collect the result), or it ran and its answer was too large to keep (IDEMPOTENCY_RESULT_NOT_KEPT; it is not run again). |
413 | Request body over 256 KB (BODY_TOO_LARGE). Tool arguments are small JSON objects. |
422 | The tool refused: it needs a confirmation step first (NEEDS_CONFIRMATION), or it declined for another reason it states (TOOL_REFUSED); result holds its explanation. Or this Idempotency-Key was used for a different tool or arguments (IDEMPOTENCY_KEY_REUSED). |
429 | Rate limited: the per-key tool-call limit (Retry-After header set), or the tool refused for a rate cap (e.g. ARTICLE_FAILURE_CAP; body carries the tool result). |
502 | Tool execution failed (TOOL_FAILED) |
503 | Temporarily unavailable, on our side, not a limit: the upstream data provider or the credit check is down (PROVIDER_UNAVAILABLE; nothing was charged), or idempotency is unavailable and the tool was NOT run (IDEMPOTENCY_UNAVAILABLE). Retry shortly. |
504 | The tool is still running past the 60s response ceiling and was not stopped (TOOL_TIMEOUT). With an Idempotency-Key, repeat the request to collect its answer. |
curl -X POST "https://app.seomatic.ai/api/v1/tools/claim_seo_task" \
-H "Authorization: Bearer $SEOMATIC_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-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 answered. result is its output, usually a JSON string (parse it). A tool that refuses does NOT answer 200: it gets the matching 402/422/429/503 below, with its own output in result. |
400 | Invalid arguments (INVALID_ARGUMENTS; details says what) or a malformed Idempotency-Key (INVALID_IDEMPOTENCY_KEY). |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA); the plan does not include acting through the API (SCOPE_REVOKED_BY_PLAN); X-Seomatic-Client is n8n or make and the workspace has no paid plan or trial (AUTOMATION_NOT_ENTITLED); the free monthly question limit is reached (FREE_QUOTA_EXCEEDED; body carries keep_going_url and a question_pack payment link); the subscription is paused or its card was declined (BILLING_INACTIVE; body links the one step that restores it, never an upgrade); or the tool refused for credits (INSUFFICIENT_CREDITS, PAYMENT_REQUIRED; body carries the tool result); or the tool hit a plan limit (the code is the refusal code itself: PROMPT_LIMIT, CADENCE_LIMIT, MONITOR_LIMIT, PAGE_LIMIT_EXCEEDED, SEAT_LIMIT_EXCEEDED, WORKSPACE_LIMIT_EXCEEDED, PLANNER_DISABLED, AUTO_EXECUTE_DISABLED, AGENT_SKILLS_NOT_ENTITLED, PAGE_TEMPLATES_NOT_ENTITLED, HOSTED_PAGES_NOT_ENTITLED, AI_ATTRIBUTION_NOT_ENTITLED, ZAPIER_NOT_ENTITLED, BYO_KEYS_NOT_ENTITLED, INCREMENTALITY_NOT_ENTITLED, WEBHOOKS_NOT_ENTITLED; `result` holds the tool refusal). Body carries upgrade_url (and reason, for tool refusals) where an upgrade is the fix. |
403 | The plan allows it but the key creator's role in the workspace does not (FORBIDDEN_ROLE; e.g. a creator now a viewer calling an acting tool). No upgrade fixes it: an admin changes the role. |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
409 | A request with this Idempotency-Key is still running (IDEMPOTENCY_IN_PROGRESS; repeat after Retry-After to collect the result), or it ran and its answer was too large to keep (IDEMPOTENCY_RESULT_NOT_KEPT; it is not run again). |
413 | Request body over 256 KB (BODY_TOO_LARGE). Tool arguments are small JSON objects. |
422 | The tool refused: it needs a confirmation step first (NEEDS_CONFIRMATION), or it declined for another reason it states (TOOL_REFUSED); result holds its explanation. Or this Idempotency-Key was used for a different tool or arguments (IDEMPOTENCY_KEY_REUSED). |
429 | Rate limited: the per-key tool-call limit (Retry-After header set), or the tool refused for a rate cap (e.g. ARTICLE_FAILURE_CAP; body carries the tool result). |
502 | Tool execution failed (TOOL_FAILED) |
503 | Temporarily unavailable, on our side, not a limit: the upstream data provider or the credit check is down (PROVIDER_UNAVAILABLE; nothing was charged), or idempotency is unavailable and the tool was NOT run (IDEMPOTENCY_UNAVAILABLE). Retry shortly. |
504 | The tool is still running past the 60s response ceiling and was not stopped (TOOL_TIMEOUT). With an Idempotency-Key, repeat the request to collect its answer. |
curl -X POST "https://app.seomatic.ai/api/v1/tools/decide_seo_task" \
-H "Authorization: Bearer $SEOMATIC_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"taskId":"…","decision":"approve"}'/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 answered. result is its output, usually a JSON string (parse it). A tool that refuses does NOT answer 200: it gets the matching 402/422/429/503 below, with its own output in result. |
400 | Invalid arguments (INVALID_ARGUMENTS; details says what) or a malformed Idempotency-Key (INVALID_IDEMPOTENCY_KEY). |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA); the plan does not include acting through the API (SCOPE_REVOKED_BY_PLAN); X-Seomatic-Client is n8n or make and the workspace has no paid plan or trial (AUTOMATION_NOT_ENTITLED); the free monthly question limit is reached (FREE_QUOTA_EXCEEDED; body carries keep_going_url and a question_pack payment link); the subscription is paused or its card was declined (BILLING_INACTIVE; body links the one step that restores it, never an upgrade); or the tool refused for credits (INSUFFICIENT_CREDITS, PAYMENT_REQUIRED; body carries the tool result); or the tool hit a plan limit (the code is the refusal code itself: PROMPT_LIMIT, CADENCE_LIMIT, MONITOR_LIMIT, PAGE_LIMIT_EXCEEDED, SEAT_LIMIT_EXCEEDED, WORKSPACE_LIMIT_EXCEEDED, PLANNER_DISABLED, AUTO_EXECUTE_DISABLED, AGENT_SKILLS_NOT_ENTITLED, PAGE_TEMPLATES_NOT_ENTITLED, HOSTED_PAGES_NOT_ENTITLED, AI_ATTRIBUTION_NOT_ENTITLED, ZAPIER_NOT_ENTITLED, BYO_KEYS_NOT_ENTITLED, INCREMENTALITY_NOT_ENTITLED, WEBHOOKS_NOT_ENTITLED; `result` holds the tool refusal). Body carries upgrade_url (and reason, for tool refusals) where an upgrade is the fix. |
403 | The plan allows it but the key creator's role in the workspace does not (FORBIDDEN_ROLE; e.g. a creator now a viewer calling an acting tool). No upgrade fixes it: an admin changes the role. |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
409 | A request with this Idempotency-Key is still running (IDEMPOTENCY_IN_PROGRESS; repeat after Retry-After to collect the result), or it ran and its answer was too large to keep (IDEMPOTENCY_RESULT_NOT_KEPT; it is not run again). |
413 | Request body over 256 KB (BODY_TOO_LARGE). Tool arguments are small JSON objects. |
422 | The tool refused: it needs a confirmation step first (NEEDS_CONFIRMATION), or it declined for another reason it states (TOOL_REFUSED); result holds its explanation. Or this Idempotency-Key was used for a different tool or arguments (IDEMPOTENCY_KEY_REUSED). |
429 | Rate limited: the per-key tool-call limit (Retry-After header set), or the tool refused for a rate cap (e.g. ARTICLE_FAILURE_CAP; body carries the tool result). |
502 | Tool execution failed (TOOL_FAILED) |
503 | Temporarily unavailable, on our side, not a limit: the upstream data provider or the credit check is down (PROVIDER_UNAVAILABLE; nothing was charged), or idempotency is unavailable and the tool was NOT run (IDEMPOTENCY_UNAVAILABLE). Retry shortly. |
504 | The tool is still running past the 60s response ceiling and was not stopped (TOOL_TIMEOUT). With an Idempotency-Key, repeat the request to collect its answer. |
curl -X POST "https://app.seomatic.ai/api/v1/tools/get_task_rollback" \
-H "Authorization: Bearer $SEOMATIC_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-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 answered. result is its output, usually a JSON string (parse it). A tool that refuses does NOT answer 200: it gets the matching 402/422/429/503 below, with its own output in result. |
400 | Invalid arguments (INVALID_ARGUMENTS; details says what) or a malformed Idempotency-Key (INVALID_IDEMPOTENCY_KEY). |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA); the plan does not include acting through the API (SCOPE_REVOKED_BY_PLAN); X-Seomatic-Client is n8n or make and the workspace has no paid plan or trial (AUTOMATION_NOT_ENTITLED); the free monthly question limit is reached (FREE_QUOTA_EXCEEDED; body carries keep_going_url and a question_pack payment link); the subscription is paused or its card was declined (BILLING_INACTIVE; body links the one step that restores it, never an upgrade); or the tool refused for credits (INSUFFICIENT_CREDITS, PAYMENT_REQUIRED; body carries the tool result); or the tool hit a plan limit (the code is the refusal code itself: PROMPT_LIMIT, CADENCE_LIMIT, MONITOR_LIMIT, PAGE_LIMIT_EXCEEDED, SEAT_LIMIT_EXCEEDED, WORKSPACE_LIMIT_EXCEEDED, PLANNER_DISABLED, AUTO_EXECUTE_DISABLED, AGENT_SKILLS_NOT_ENTITLED, PAGE_TEMPLATES_NOT_ENTITLED, HOSTED_PAGES_NOT_ENTITLED, AI_ATTRIBUTION_NOT_ENTITLED, ZAPIER_NOT_ENTITLED, BYO_KEYS_NOT_ENTITLED, INCREMENTALITY_NOT_ENTITLED, WEBHOOKS_NOT_ENTITLED; `result` holds the tool refusal). Body carries upgrade_url (and reason, for tool refusals) where an upgrade is the fix. |
403 | The plan allows it but the key creator's role in the workspace does not (FORBIDDEN_ROLE; e.g. a creator now a viewer calling an acting tool). No upgrade fixes it: an admin changes the role. |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
409 | A request with this Idempotency-Key is still running (IDEMPOTENCY_IN_PROGRESS; repeat after Retry-After to collect the result), or it ran and its answer was too large to keep (IDEMPOTENCY_RESULT_NOT_KEPT; it is not run again). |
413 | Request body over 256 KB (BODY_TOO_LARGE). Tool arguments are small JSON objects. |
422 | The tool refused: it needs a confirmation step first (NEEDS_CONFIRMATION), or it declined for another reason it states (TOOL_REFUSED); result holds its explanation. Or this Idempotency-Key was used for a different tool or arguments (IDEMPOTENCY_KEY_REUSED). |
429 | Rate limited: the per-key tool-call limit (Retry-After header set), or the tool refused for a rate cap (e.g. ARTICLE_FAILURE_CAP; body carries the tool result). |
502 | Tool execution failed (TOOL_FAILED) |
503 | Temporarily unavailable, on our side, not a limit: the upstream data provider or the credit check is down (PROVIDER_UNAVAILABLE; nothing was charged), or idempotency is unavailable and the tool was NOT run (IDEMPOTENCY_UNAVAILABLE). Retry shortly. |
504 | The tool is still running past the 60s response ceiling and was not stopped (TOOL_TIMEOUT). With an Idempotency-Key, repeat the request to collect its answer. |
curl -X POST "https://app.seomatic.ai/api/v1/tools/score_draft" \
-H "Authorization: Bearer $SEOMATIC_API_KEY" \
-H "Content-Type: application/json" \
-d '{"content":"…"}'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 answered. result is its output, usually a JSON string (parse it). A tool that refuses does NOT answer 200: it gets the matching 402/422/429/503 below, with its own output in result. |
400 | Invalid arguments (INVALID_ARGUMENTS; details says what) or a malformed Idempotency-Key (INVALID_IDEMPOTENCY_KEY). |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA); the plan does not include acting through the API (SCOPE_REVOKED_BY_PLAN); X-Seomatic-Client is n8n or make and the workspace has no paid plan or trial (AUTOMATION_NOT_ENTITLED); the free monthly question limit is reached (FREE_QUOTA_EXCEEDED; body carries keep_going_url and a question_pack payment link); the subscription is paused or its card was declined (BILLING_INACTIVE; body links the one step that restores it, never an upgrade); or the tool refused for credits (INSUFFICIENT_CREDITS, PAYMENT_REQUIRED; body carries the tool result); or the tool hit a plan limit (the code is the refusal code itself: PROMPT_LIMIT, CADENCE_LIMIT, MONITOR_LIMIT, PAGE_LIMIT_EXCEEDED, SEAT_LIMIT_EXCEEDED, WORKSPACE_LIMIT_EXCEEDED, PLANNER_DISABLED, AUTO_EXECUTE_DISABLED, AGENT_SKILLS_NOT_ENTITLED, PAGE_TEMPLATES_NOT_ENTITLED, HOSTED_PAGES_NOT_ENTITLED, AI_ATTRIBUTION_NOT_ENTITLED, ZAPIER_NOT_ENTITLED, BYO_KEYS_NOT_ENTITLED, INCREMENTALITY_NOT_ENTITLED, WEBHOOKS_NOT_ENTITLED; `result` holds the tool refusal). Body carries upgrade_url (and reason, for tool refusals) where an upgrade is the fix. |
403 | The plan allows it but the key creator's role in the workspace does not (FORBIDDEN_ROLE; e.g. a creator now a viewer calling an acting tool). No upgrade fixes it: an admin changes the role. |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
409 | A request with this Idempotency-Key is still running (IDEMPOTENCY_IN_PROGRESS; repeat after Retry-After to collect the result), or it ran and its answer was too large to keep (IDEMPOTENCY_RESULT_NOT_KEPT; it is not run again). |
413 | Request body over 256 KB (BODY_TOO_LARGE). Tool arguments are small JSON objects. |
422 | The tool refused: it needs a confirmation step first (NEEDS_CONFIRMATION), or it declined for another reason it states (TOOL_REFUSED); result holds its explanation. Or this Idempotency-Key was used for a different tool or arguments (IDEMPOTENCY_KEY_REUSED). |
429 | Rate limited: the per-key tool-call limit (Retry-After header set), or the tool refused for a rate cap (e.g. ARTICLE_FAILURE_CAP; body carries the tool result). |
502 | Tool execution failed (TOOL_FAILED) |
503 | Temporarily unavailable, on our side, not a limit: the upstream data provider or the credit check is down (PROVIDER_UNAVAILABLE; nothing was charged), or idempotency is unavailable and the tool was NOT run (IDEMPOTENCY_UNAVAILABLE). Retry shortly. |
504 | The tool is still running past the 60s response ceiling and was not stopped (TOOL_TIMEOUT). With an Idempotency-Key, repeat the request to collect its answer. |
curl -X POST "https://app.seomatic.ai/api/v1/tools/list_seo_campaigns" \
-H "Authorization: Bearer $SEOMATIC_API_KEY" \
-H "Idempotency-Key: $(uuidgen)"/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 answered. result is its output, usually a JSON string (parse it). A tool that refuses does NOT answer 200: it gets the matching 402/422/429/503 below, with its own output in result. |
400 | Invalid arguments (INVALID_ARGUMENTS; details says what) or a malformed Idempotency-Key (INVALID_IDEMPOTENCY_KEY). |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA); the plan does not include acting through the API (SCOPE_REVOKED_BY_PLAN); X-Seomatic-Client is n8n or make and the workspace has no paid plan or trial (AUTOMATION_NOT_ENTITLED); the free monthly question limit is reached (FREE_QUOTA_EXCEEDED; body carries keep_going_url and a question_pack payment link); the subscription is paused or its card was declined (BILLING_INACTIVE; body links the one step that restores it, never an upgrade); or the tool refused for credits (INSUFFICIENT_CREDITS, PAYMENT_REQUIRED; body carries the tool result); or the tool hit a plan limit (the code is the refusal code itself: PROMPT_LIMIT, CADENCE_LIMIT, MONITOR_LIMIT, PAGE_LIMIT_EXCEEDED, SEAT_LIMIT_EXCEEDED, WORKSPACE_LIMIT_EXCEEDED, PLANNER_DISABLED, AUTO_EXECUTE_DISABLED, AGENT_SKILLS_NOT_ENTITLED, PAGE_TEMPLATES_NOT_ENTITLED, HOSTED_PAGES_NOT_ENTITLED, AI_ATTRIBUTION_NOT_ENTITLED, ZAPIER_NOT_ENTITLED, BYO_KEYS_NOT_ENTITLED, INCREMENTALITY_NOT_ENTITLED, WEBHOOKS_NOT_ENTITLED; `result` holds the tool refusal). Body carries upgrade_url (and reason, for tool refusals) where an upgrade is the fix. |
403 | The plan allows it but the key creator's role in the workspace does not (FORBIDDEN_ROLE; e.g. a creator now a viewer calling an acting tool). No upgrade fixes it: an admin changes the role. |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
409 | A request with this Idempotency-Key is still running (IDEMPOTENCY_IN_PROGRESS; repeat after Retry-After to collect the result), or it ran and its answer was too large to keep (IDEMPOTENCY_RESULT_NOT_KEPT; it is not run again). |
413 | Request body over 256 KB (BODY_TOO_LARGE). Tool arguments are small JSON objects. |
422 | The tool refused: it needs a confirmation step first (NEEDS_CONFIRMATION), or it declined for another reason it states (TOOL_REFUSED); result holds its explanation. Or this Idempotency-Key was used for a different tool or arguments (IDEMPOTENCY_KEY_REUSED). |
429 | Rate limited: the per-key tool-call limit (Retry-After header set), or the tool refused for a rate cap (e.g. ARTICLE_FAILURE_CAP; body carries the tool result). |
502 | Tool execution failed (TOOL_FAILED) |
503 | Temporarily unavailable, on our side, not a limit: the upstream data provider or the credit check is down (PROVIDER_UNAVAILABLE; nothing was charged), or idempotency is unavailable and the tool was NOT run (IDEMPOTENCY_UNAVAILABLE). Retry shortly. |
504 | The tool is still running past the 60s response ceiling and was not stopped (TOOL_TIMEOUT). With an Idempotency-Key, repeat the request to collect its answer. |
curl -X POST "https://app.seomatic.ai/api/v1/tools/manage_campaign" \
-H "Authorization: Bearer $SEOMATIC_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"campaignId":"00000000-0000-0000-0000-000000000000","action":"approve"}'/tools/propose_page_scale_campaignactsStage a set of pages built on the customer's own page or own template (e.g. "a page for each town we serve", "one page per product line"). We never design a page for them and never use a built-in des…
| Name | Type | Required | Description |
|---|---|---|---|
title | string | yes | |
kind | string | yes | What kind of pages, e.g. "location pages", "service area pages", "product line pages" |
brief | string | yes | What the user asked for, in their words: audience, what each page must say, tone |
exemplarUrl | string | no | One of the customer's own pages (http URL in their site inventory) the new pages are modelled on. Required unless proje… |
projectId | string | no | One of the customer's own projects whose fields hold their {{Column}} template (find it with list_projects). Required u… |
rowSourceKind | enum: user | library | gbp_locations | evidence | no | Where the rows come from. Required with exemplarUrl; with projectId it defaults to the dataset already attached to that… |
entities | string[] | no | rowSourceKind=evidence: the entities the user named, one per intended page, exactly as they said them ('Chapeltown', 'R… |
sourceUrls | string[] | no | rowSourceKind=evidence: public pages the user named as sources (a council planning guide, a regulator's page, a trade b… |
rows | object[] | no | rowSourceKind=user: the rows, one object per page (name + the facts the user gave: city, region, address, phone, hours,… |
libraryDatasetId | string | no | rowSourceKind=library: the dataset id (list_datasets) |
rowTarget | integer | no | |
allowGenText | boolean | no | Project mode: the template may carry per-row AI text badges (costs credits per page; the human sees the cost at gate 2) |
publishAsDraft | boolean | no |
| Status | Description |
|---|---|
200 | { tool, result }: the tool answered. result is its output, usually a JSON string (parse it). A tool that refuses does NOT answer 200: it gets the matching 402/422/429/503 below, with its own output in result. |
400 | Invalid arguments (INVALID_ARGUMENTS; details says what) or a malformed Idempotency-Key (INVALID_IDEMPOTENCY_KEY). |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA); the plan does not include acting through the API (SCOPE_REVOKED_BY_PLAN); X-Seomatic-Client is n8n or make and the workspace has no paid plan or trial (AUTOMATION_NOT_ENTITLED); the free monthly question limit is reached (FREE_QUOTA_EXCEEDED; body carries keep_going_url and a question_pack payment link); the subscription is paused or its card was declined (BILLING_INACTIVE; body links the one step that restores it, never an upgrade); or the tool refused for credits (INSUFFICIENT_CREDITS, PAYMENT_REQUIRED; body carries the tool result); or the tool hit a plan limit (the code is the refusal code itself: PROMPT_LIMIT, CADENCE_LIMIT, MONITOR_LIMIT, PAGE_LIMIT_EXCEEDED, SEAT_LIMIT_EXCEEDED, WORKSPACE_LIMIT_EXCEEDED, PLANNER_DISABLED, AUTO_EXECUTE_DISABLED, AGENT_SKILLS_NOT_ENTITLED, PAGE_TEMPLATES_NOT_ENTITLED, HOSTED_PAGES_NOT_ENTITLED, AI_ATTRIBUTION_NOT_ENTITLED, ZAPIER_NOT_ENTITLED, BYO_KEYS_NOT_ENTITLED, INCREMENTALITY_NOT_ENTITLED, WEBHOOKS_NOT_ENTITLED; `result` holds the tool refusal). Body carries upgrade_url (and reason, for tool refusals) where an upgrade is the fix. |
403 | The plan allows it but the key creator's role in the workspace does not (FORBIDDEN_ROLE; e.g. a creator now a viewer calling an acting tool). No upgrade fixes it: an admin changes the role. |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
409 | A request with this Idempotency-Key is still running (IDEMPOTENCY_IN_PROGRESS; repeat after Retry-After to collect the result), or it ran and its answer was too large to keep (IDEMPOTENCY_RESULT_NOT_KEPT; it is not run again). |
413 | Request body over 256 KB (BODY_TOO_LARGE). Tool arguments are small JSON objects. |
422 | The tool refused: it needs a confirmation step first (NEEDS_CONFIRMATION), or it declined for another reason it states (TOOL_REFUSED); result holds its explanation. Or this Idempotency-Key was used for a different tool or arguments (IDEMPOTENCY_KEY_REUSED). |
429 | Rate limited: the per-key tool-call limit (Retry-After header set), or the tool refused for a rate cap (e.g. ARTICLE_FAILURE_CAP; body carries the tool result). |
502 | Tool execution failed (TOOL_FAILED) |
503 | Temporarily unavailable, on our side, not a limit: the upstream data provider or the credit check is down (PROVIDER_UNAVAILABLE; nothing was charged), or idempotency is unavailable and the tool was NOT run (IDEMPOTENCY_UNAVAILABLE). Retry shortly. |
504 | The tool is still running past the 60s response ceiling and was not stopped (TOOL_TIMEOUT). With an Idempotency-Key, repeat the request to collect its answer. |
curl -X POST "https://app.seomatic.ai/api/v1/tools/propose_page_scale_campaign" \
-H "Authorization: Bearer $SEOMATIC_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"title":"…","kind":"…","brief":"…"}'/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 answered. result is its output, usually a JSON string (parse it). A tool that refuses does NOT answer 200: it gets the matching 402/422/429/503 below, with its own output in result. |
400 | Invalid arguments (INVALID_ARGUMENTS; details says what) or a malformed Idempotency-Key (INVALID_IDEMPOTENCY_KEY). |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA); the plan does not include acting through the API (SCOPE_REVOKED_BY_PLAN); X-Seomatic-Client is n8n or make and the workspace has no paid plan or trial (AUTOMATION_NOT_ENTITLED); the free monthly question limit is reached (FREE_QUOTA_EXCEEDED; body carries keep_going_url and a question_pack payment link); the subscription is paused or its card was declined (BILLING_INACTIVE; body links the one step that restores it, never an upgrade); or the tool refused for credits (INSUFFICIENT_CREDITS, PAYMENT_REQUIRED; body carries the tool result); or the tool hit a plan limit (the code is the refusal code itself: PROMPT_LIMIT, CADENCE_LIMIT, MONITOR_LIMIT, PAGE_LIMIT_EXCEEDED, SEAT_LIMIT_EXCEEDED, WORKSPACE_LIMIT_EXCEEDED, PLANNER_DISABLED, AUTO_EXECUTE_DISABLED, AGENT_SKILLS_NOT_ENTITLED, PAGE_TEMPLATES_NOT_ENTITLED, HOSTED_PAGES_NOT_ENTITLED, AI_ATTRIBUTION_NOT_ENTITLED, ZAPIER_NOT_ENTITLED, BYO_KEYS_NOT_ENTITLED, INCREMENTALITY_NOT_ENTITLED, WEBHOOKS_NOT_ENTITLED; `result` holds the tool refusal). Body carries upgrade_url (and reason, for tool refusals) where an upgrade is the fix. |
403 | The plan allows it but the key creator's role in the workspace does not (FORBIDDEN_ROLE; e.g. a creator now a viewer calling an acting tool). No upgrade fixes it: an admin changes the role. |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
409 | A request with this Idempotency-Key is still running (IDEMPOTENCY_IN_PROGRESS; repeat after Retry-After to collect the result), or it ran and its answer was too large to keep (IDEMPOTENCY_RESULT_NOT_KEPT; it is not run again). |
413 | Request body over 256 KB (BODY_TOO_LARGE). Tool arguments are small JSON objects. |
422 | The tool refused: it needs a confirmation step first (NEEDS_CONFIRMATION), or it declined for another reason it states (TOOL_REFUSED); result holds its explanation. Or this Idempotency-Key was used for a different tool or arguments (IDEMPOTENCY_KEY_REUSED). |
429 | Rate limited: the per-key tool-call limit (Retry-After header set), or the tool refused for a rate cap (e.g. ARTICLE_FAILURE_CAP; body carries the tool result). |
502 | Tool execution failed (TOOL_FAILED) |
503 | Temporarily unavailable, on our side, not a limit: the upstream data provider or the credit check is down (PROVIDER_UNAVAILABLE; nothing was charged), or idempotency is unavailable and the tool was NOT run (IDEMPOTENCY_UNAVAILABLE). Retry shortly. |
504 | The tool is still running past the 60s response ceiling and was not stopped (TOOL_TIMEOUT). With an Idempotency-Key, repeat the request to collect its answer. |
curl -X POST "https://app.seomatic.ai/api/v1/tools/propose_content_sweep_campaign" \
-H "Authorization: Bearer $SEOMATIC_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"title":"…","topics":[]}'/tools/propose_location_pagesactsStage a batch of location pages built on the customer's own site, page type and layout. mode 'create': new pages modelled on one of their pages (exemplarUrl, ideally an existing location page): each…
| Name | Type | Required | Description |
|---|---|---|---|
mode | enum: create | enrich | yes | |
exemplarUrl | string | no | create: the customer's page the new pages are modelled on (its layout, embeds and page type). |
exemplarPlace | string | no | create: the place the model page is about, when its title does not say (e.g. "Dublin"). |
title | string | no | |
rows | object[] | yes | One object per location: name (required), and the facts the user gave: city, region, country, address, phone, email, ho… |
| Status | Description |
|---|---|
200 | { tool, result }: the tool answered. result is its output, usually a JSON string (parse it). A tool that refuses does NOT answer 200: it gets the matching 402/422/429/503 below, with its own output in result. |
400 | Invalid arguments (INVALID_ARGUMENTS; details says what) or a malformed Idempotency-Key (INVALID_IDEMPOTENCY_KEY). |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA); the plan does not include acting through the API (SCOPE_REVOKED_BY_PLAN); X-Seomatic-Client is n8n or make and the workspace has no paid plan or trial (AUTOMATION_NOT_ENTITLED); the free monthly question limit is reached (FREE_QUOTA_EXCEEDED; body carries keep_going_url and a question_pack payment link); the subscription is paused or its card was declined (BILLING_INACTIVE; body links the one step that restores it, never an upgrade); or the tool refused for credits (INSUFFICIENT_CREDITS, PAYMENT_REQUIRED; body carries the tool result); or the tool hit a plan limit (the code is the refusal code itself: PROMPT_LIMIT, CADENCE_LIMIT, MONITOR_LIMIT, PAGE_LIMIT_EXCEEDED, SEAT_LIMIT_EXCEEDED, WORKSPACE_LIMIT_EXCEEDED, PLANNER_DISABLED, AUTO_EXECUTE_DISABLED, AGENT_SKILLS_NOT_ENTITLED, PAGE_TEMPLATES_NOT_ENTITLED, HOSTED_PAGES_NOT_ENTITLED, AI_ATTRIBUTION_NOT_ENTITLED, ZAPIER_NOT_ENTITLED, BYO_KEYS_NOT_ENTITLED, INCREMENTALITY_NOT_ENTITLED, WEBHOOKS_NOT_ENTITLED; `result` holds the tool refusal). Body carries upgrade_url (and reason, for tool refusals) where an upgrade is the fix. |
403 | The plan allows it but the key creator's role in the workspace does not (FORBIDDEN_ROLE; e.g. a creator now a viewer calling an acting tool). No upgrade fixes it: an admin changes the role. |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
409 | A request with this Idempotency-Key is still running (IDEMPOTENCY_IN_PROGRESS; repeat after Retry-After to collect the result), or it ran and its answer was too large to keep (IDEMPOTENCY_RESULT_NOT_KEPT; it is not run again). |
413 | Request body over 256 KB (BODY_TOO_LARGE). Tool arguments are small JSON objects. |
422 | The tool refused: it needs a confirmation step first (NEEDS_CONFIRMATION), or it declined for another reason it states (TOOL_REFUSED); result holds its explanation. Or this Idempotency-Key was used for a different tool or arguments (IDEMPOTENCY_KEY_REUSED). |
429 | Rate limited: the per-key tool-call limit (Retry-After header set), or the tool refused for a rate cap (e.g. ARTICLE_FAILURE_CAP; body carries the tool result). |
502 | Tool execution failed (TOOL_FAILED) |
503 | Temporarily unavailable, on our side, not a limit: the upstream data provider or the credit check is down (PROVIDER_UNAVAILABLE; nothing was charged), or idempotency is unavailable and the tool was NOT run (IDEMPOTENCY_UNAVAILABLE). Retry shortly. |
504 | The tool is still running past the 60s response ceiling and was not stopped (TOOL_TIMEOUT). With an Idempotency-Key, repeat the request to collect its answer. |
curl -X POST "https://app.seomatic.ai/api/v1/tools/propose_location_pages" \
-H "Authorization: Bearer $SEOMATIC_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"mode":"create","rows":[]}'/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 answered. result is its output, usually a JSON string (parse it). A tool that refuses does NOT answer 200: it gets the matching 402/422/429/503 below, with its own output in result. |
400 | Invalid arguments (INVALID_ARGUMENTS; details says what) or a malformed Idempotency-Key (INVALID_IDEMPOTENCY_KEY). |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA); the plan does not include acting through the API (SCOPE_REVOKED_BY_PLAN); X-Seomatic-Client is n8n or make and the workspace has no paid plan or trial (AUTOMATION_NOT_ENTITLED); the free monthly question limit is reached (FREE_QUOTA_EXCEEDED; body carries keep_going_url and a question_pack payment link); the subscription is paused or its card was declined (BILLING_INACTIVE; body links the one step that restores it, never an upgrade); or the tool refused for credits (INSUFFICIENT_CREDITS, PAYMENT_REQUIRED; body carries the tool result); or the tool hit a plan limit (the code is the refusal code itself: PROMPT_LIMIT, CADENCE_LIMIT, MONITOR_LIMIT, PAGE_LIMIT_EXCEEDED, SEAT_LIMIT_EXCEEDED, WORKSPACE_LIMIT_EXCEEDED, PLANNER_DISABLED, AUTO_EXECUTE_DISABLED, AGENT_SKILLS_NOT_ENTITLED, PAGE_TEMPLATES_NOT_ENTITLED, HOSTED_PAGES_NOT_ENTITLED, AI_ATTRIBUTION_NOT_ENTITLED, ZAPIER_NOT_ENTITLED, BYO_KEYS_NOT_ENTITLED, INCREMENTALITY_NOT_ENTITLED, WEBHOOKS_NOT_ENTITLED; `result` holds the tool refusal). Body carries upgrade_url (and reason, for tool refusals) where an upgrade is the fix. |
403 | The plan allows it but the key creator's role in the workspace does not (FORBIDDEN_ROLE; e.g. a creator now a viewer calling an acting tool). No upgrade fixes it: an admin changes the role. |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
409 | A request with this Idempotency-Key is still running (IDEMPOTENCY_IN_PROGRESS; repeat after Retry-After to collect the result), or it ran and its answer was too large to keep (IDEMPOTENCY_RESULT_NOT_KEPT; it is not run again). |
413 | Request body over 256 KB (BODY_TOO_LARGE). Tool arguments are small JSON objects. |
422 | The tool refused: it needs a confirmation step first (NEEDS_CONFIRMATION), or it declined for another reason it states (TOOL_REFUSED); result holds its explanation. Or this Idempotency-Key was used for a different tool or arguments (IDEMPOTENCY_KEY_REUSED). |
429 | Rate limited: the per-key tool-call limit (Retry-After header set), or the tool refused for a rate cap (e.g. ARTICLE_FAILURE_CAP; body carries the tool result). |
502 | Tool execution failed (TOOL_FAILED) |
503 | Temporarily unavailable, on our side, not a limit: the upstream data provider or the credit check is down (PROVIDER_UNAVAILABLE; nothing was charged), or idempotency is unavailable and the tool was NOT run (IDEMPOTENCY_UNAVAILABLE). Retry shortly. |
504 | The tool is still running past the 60s response ceiling and was not stopped (TOOL_TIMEOUT). With an Idempotency-Key, repeat the request to collect its answer. |
curl -X POST "https://app.seomatic.ai/api/v1/tools/create_bulk_edit_campaign" \
-H "Authorization: Bearer $SEOMATIC_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"taskType":"ctr_fix"}'/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 TRUE (founder decision 2026-10-06): articles that pass the quality gate and the reviewer publish on their own,… |
| Status | Description |
|---|---|
200 | { tool, result }: the tool answered. result is its output, usually a JSON string (parse it). A tool that refuses does NOT answer 200: it gets the matching 402/422/429/503 below, with its own output in result. |
400 | Invalid arguments (INVALID_ARGUMENTS; details says what) or a malformed Idempotency-Key (INVALID_IDEMPOTENCY_KEY). |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA); the plan does not include acting through the API (SCOPE_REVOKED_BY_PLAN); X-Seomatic-Client is n8n or make and the workspace has no paid plan or trial (AUTOMATION_NOT_ENTITLED); the free monthly question limit is reached (FREE_QUOTA_EXCEEDED; body carries keep_going_url and a question_pack payment link); the subscription is paused or its card was declined (BILLING_INACTIVE; body links the one step that restores it, never an upgrade); or the tool refused for credits (INSUFFICIENT_CREDITS, PAYMENT_REQUIRED; body carries the tool result); or the tool hit a plan limit (the code is the refusal code itself: PROMPT_LIMIT, CADENCE_LIMIT, MONITOR_LIMIT, PAGE_LIMIT_EXCEEDED, SEAT_LIMIT_EXCEEDED, WORKSPACE_LIMIT_EXCEEDED, PLANNER_DISABLED, AUTO_EXECUTE_DISABLED, AGENT_SKILLS_NOT_ENTITLED, PAGE_TEMPLATES_NOT_ENTITLED, HOSTED_PAGES_NOT_ENTITLED, AI_ATTRIBUTION_NOT_ENTITLED, ZAPIER_NOT_ENTITLED, BYO_KEYS_NOT_ENTITLED, INCREMENTALITY_NOT_ENTITLED, WEBHOOKS_NOT_ENTITLED; `result` holds the tool refusal). Body carries upgrade_url (and reason, for tool refusals) where an upgrade is the fix. |
403 | The plan allows it but the key creator's role in the workspace does not (FORBIDDEN_ROLE; e.g. a creator now a viewer calling an acting tool). No upgrade fixes it: an admin changes the role. |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
409 | A request with this Idempotency-Key is still running (IDEMPOTENCY_IN_PROGRESS; repeat after Retry-After to collect the result), or it ran and its answer was too large to keep (IDEMPOTENCY_RESULT_NOT_KEPT; it is not run again). |
413 | Request body over 256 KB (BODY_TOO_LARGE). Tool arguments are small JSON objects. |
422 | The tool refused: it needs a confirmation step first (NEEDS_CONFIRMATION), or it declined for another reason it states (TOOL_REFUSED); result holds its explanation. Or this Idempotency-Key was used for a different tool or arguments (IDEMPOTENCY_KEY_REUSED). |
429 | Rate limited: the per-key tool-call limit (Retry-After header set), or the tool refused for a rate cap (e.g. ARTICLE_FAILURE_CAP; body carries the tool result). |
502 | Tool execution failed (TOOL_FAILED) |
503 | Temporarily unavailable, on our side, not a limit: the upstream data provider or the credit check is down (PROVIDER_UNAVAILABLE; nothing was charged), or idempotency is unavailable and the tool was NOT run (IDEMPOTENCY_UNAVAILABLE). Retry shortly. |
504 | The tool is still running past the 60s response ceiling and was not stopped (TOOL_TIMEOUT). With an Idempotency-Key, repeat the request to collect its answer. |
curl -X POST "https://app.seomatic.ai/api/v1/tools/write_blog_articles" \
-H "Authorization: Bearer $SEOMATIC_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"topics":[]}'/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 answered. result is its output, usually a JSON string (parse it). A tool that refuses does NOT answer 200: it gets the matching 402/422/429/503 below, with its own output in result. |
400 | Invalid arguments (INVALID_ARGUMENTS; details says what) or a malformed Idempotency-Key (INVALID_IDEMPOTENCY_KEY). |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA); the plan does not include acting through the API (SCOPE_REVOKED_BY_PLAN); X-Seomatic-Client is n8n or make and the workspace has no paid plan or trial (AUTOMATION_NOT_ENTITLED); the free monthly question limit is reached (FREE_QUOTA_EXCEEDED; body carries keep_going_url and a question_pack payment link); the subscription is paused or its card was declined (BILLING_INACTIVE; body links the one step that restores it, never an upgrade); or the tool refused for credits (INSUFFICIENT_CREDITS, PAYMENT_REQUIRED; body carries the tool result); or the tool hit a plan limit (the code is the refusal code itself: PROMPT_LIMIT, CADENCE_LIMIT, MONITOR_LIMIT, PAGE_LIMIT_EXCEEDED, SEAT_LIMIT_EXCEEDED, WORKSPACE_LIMIT_EXCEEDED, PLANNER_DISABLED, AUTO_EXECUTE_DISABLED, AGENT_SKILLS_NOT_ENTITLED, PAGE_TEMPLATES_NOT_ENTITLED, HOSTED_PAGES_NOT_ENTITLED, AI_ATTRIBUTION_NOT_ENTITLED, ZAPIER_NOT_ENTITLED, BYO_KEYS_NOT_ENTITLED, INCREMENTALITY_NOT_ENTITLED, WEBHOOKS_NOT_ENTITLED; `result` holds the tool refusal). Body carries upgrade_url (and reason, for tool refusals) where an upgrade is the fix. |
403 | The plan allows it but the key creator's role in the workspace does not (FORBIDDEN_ROLE; e.g. a creator now a viewer calling an acting tool). No upgrade fixes it: an admin changes the role. |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
409 | A request with this Idempotency-Key is still running (IDEMPOTENCY_IN_PROGRESS; repeat after Retry-After to collect the result), or it ran and its answer was too large to keep (IDEMPOTENCY_RESULT_NOT_KEPT; it is not run again). |
413 | Request body over 256 KB (BODY_TOO_LARGE). Tool arguments are small JSON objects. |
422 | The tool refused: it needs a confirmation step first (NEEDS_CONFIRMATION), or it declined for another reason it states (TOOL_REFUSED); result holds its explanation. Or this Idempotency-Key was used for a different tool or arguments (IDEMPOTENCY_KEY_REUSED). |
429 | Rate limited: the per-key tool-call limit (Retry-After header set), or the tool refused for a rate cap (e.g. ARTICLE_FAILURE_CAP; body carries the tool result). |
502 | Tool execution failed (TOOL_FAILED) |
503 | Temporarily unavailable, on our side, not a limit: the upstream data provider or the credit check is down (PROVIDER_UNAVAILABLE; nothing was charged), or idempotency is unavailable and the tool was NOT run (IDEMPOTENCY_UNAVAILABLE). Retry shortly. |
504 | The tool is still running past the 60s response ceiling and was not stopped (TOOL_TIMEOUT). With an Idempotency-Key, repeat the request to collect its answer. |
curl -X POST "https://app.seomatic.ai/api/v1/tools/save_blog_article" \
-H "Authorization: Bearer $SEOMATIC_API_KEY" \
-H "Content-Type: application/json" \
-d '{"title":"…","content":"…","slug":"…","excerpt":"…","featuredImagePrompt":"…"}'The library that powers programmatic pages.
/tools/find_page_set_patternsreadKeyword research for A page set (2026-10-07). Finds, in this site's real Search Console queries (and, with a seed, the keyword provider's suggestions around it), the templates people repeat with one…
| Name | Type | Required | Description |
|---|---|---|---|
seed | string | no | A head term to research with the keyword provider ('signage', 'orthodontist', 'accounting software'); costs a few credi… |
minEntities | integer | no | Smallest set worth showing (default 5). |
| Status | Description |
|---|---|
200 | { tool, result }: the tool answered. result is its output, usually a JSON string (parse it). A tool that refuses does NOT answer 200: it gets the matching 402/422/429/503 below, with its own output in result. |
400 | Invalid arguments (INVALID_ARGUMENTS; details says what) or a malformed Idempotency-Key (INVALID_IDEMPOTENCY_KEY). |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA); the plan does not include acting through the API (SCOPE_REVOKED_BY_PLAN); X-Seomatic-Client is n8n or make and the workspace has no paid plan or trial (AUTOMATION_NOT_ENTITLED); the free monthly question limit is reached (FREE_QUOTA_EXCEEDED; body carries keep_going_url and a question_pack payment link); the subscription is paused or its card was declined (BILLING_INACTIVE; body links the one step that restores it, never an upgrade); or the tool refused for credits (INSUFFICIENT_CREDITS, PAYMENT_REQUIRED; body carries the tool result); or the tool hit a plan limit (the code is the refusal code itself: PROMPT_LIMIT, CADENCE_LIMIT, MONITOR_LIMIT, PAGE_LIMIT_EXCEEDED, SEAT_LIMIT_EXCEEDED, WORKSPACE_LIMIT_EXCEEDED, PLANNER_DISABLED, AUTO_EXECUTE_DISABLED, AGENT_SKILLS_NOT_ENTITLED, PAGE_TEMPLATES_NOT_ENTITLED, HOSTED_PAGES_NOT_ENTITLED, AI_ATTRIBUTION_NOT_ENTITLED, ZAPIER_NOT_ENTITLED, BYO_KEYS_NOT_ENTITLED, INCREMENTALITY_NOT_ENTITLED, WEBHOOKS_NOT_ENTITLED; `result` holds the tool refusal). Body carries upgrade_url (and reason, for tool refusals) where an upgrade is the fix. |
403 | The plan allows it but the key creator's role in the workspace does not (FORBIDDEN_ROLE; e.g. a creator now a viewer calling an acting tool). No upgrade fixes it: an admin changes the role. |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
409 | A request with this Idempotency-Key is still running (IDEMPOTENCY_IN_PROGRESS; repeat after Retry-After to collect the result), or it ran and its answer was too large to keep (IDEMPOTENCY_RESULT_NOT_KEPT; it is not run again). |
413 | Request body over 256 KB (BODY_TOO_LARGE). Tool arguments are small JSON objects. |
422 | The tool refused: it needs a confirmation step first (NEEDS_CONFIRMATION), or it declined for another reason it states (TOOL_REFUSED); result holds its explanation. Or this Idempotency-Key was used for a different tool or arguments (IDEMPOTENCY_KEY_REUSED). |
429 | Rate limited: the per-key tool-call limit (Retry-After header set), or the tool refused for a rate cap (e.g. ARTICLE_FAILURE_CAP; body carries the tool result). |
502 | Tool execution failed (TOOL_FAILED) |
503 | Temporarily unavailable, on our side, not a limit: the upstream data provider or the credit check is down (PROVIDER_UNAVAILABLE; nothing was charged), or idempotency is unavailable and the tool was NOT run (IDEMPOTENCY_UNAVAILABLE). Retry shortly. |
504 | The tool is still running past the 60s response ceiling and was not stopped (TOOL_TIMEOUT). With an Idempotency-Key, repeat the request to collect its answer. |
curl -X POST "https://app.seomatic.ai/api/v1/tools/find_page_set_patterns" \
-H "Authorization: Bearer $SEOMATIC_API_KEY"/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 answered. result is its output, usually a JSON string (parse it). A tool that refuses does NOT answer 200: it gets the matching 402/422/429/503 below, with its own output in result. |
400 | Invalid arguments (INVALID_ARGUMENTS; details says what) or a malformed Idempotency-Key (INVALID_IDEMPOTENCY_KEY). |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA); the plan does not include acting through the API (SCOPE_REVOKED_BY_PLAN); X-Seomatic-Client is n8n or make and the workspace has no paid plan or trial (AUTOMATION_NOT_ENTITLED); the free monthly question limit is reached (FREE_QUOTA_EXCEEDED; body carries keep_going_url and a question_pack payment link); the subscription is paused or its card was declined (BILLING_INACTIVE; body links the one step that restores it, never an upgrade); or the tool refused for credits (INSUFFICIENT_CREDITS, PAYMENT_REQUIRED; body carries the tool result); or the tool hit a plan limit (the code is the refusal code itself: PROMPT_LIMIT, CADENCE_LIMIT, MONITOR_LIMIT, PAGE_LIMIT_EXCEEDED, SEAT_LIMIT_EXCEEDED, WORKSPACE_LIMIT_EXCEEDED, PLANNER_DISABLED, AUTO_EXECUTE_DISABLED, AGENT_SKILLS_NOT_ENTITLED, PAGE_TEMPLATES_NOT_ENTITLED, HOSTED_PAGES_NOT_ENTITLED, AI_ATTRIBUTION_NOT_ENTITLED, ZAPIER_NOT_ENTITLED, BYO_KEYS_NOT_ENTITLED, INCREMENTALITY_NOT_ENTITLED, WEBHOOKS_NOT_ENTITLED; `result` holds the tool refusal). Body carries upgrade_url (and reason, for tool refusals) where an upgrade is the fix. |
403 | The plan allows it but the key creator's role in the workspace does not (FORBIDDEN_ROLE; e.g. a creator now a viewer calling an acting tool). No upgrade fixes it: an admin changes the role. |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
409 | A request with this Idempotency-Key is still running (IDEMPOTENCY_IN_PROGRESS; repeat after Retry-After to collect the result), or it ran and its answer was too large to keep (IDEMPOTENCY_RESULT_NOT_KEPT; it is not run again). |
413 | Request body over 256 KB (BODY_TOO_LARGE). Tool arguments are small JSON objects. |
422 | The tool refused: it needs a confirmation step first (NEEDS_CONFIRMATION), or it declined for another reason it states (TOOL_REFUSED); result holds its explanation. Or this Idempotency-Key was used for a different tool or arguments (IDEMPOTENCY_KEY_REUSED). |
429 | Rate limited: the per-key tool-call limit (Retry-After header set), or the tool refused for a rate cap (e.g. ARTICLE_FAILURE_CAP; body carries the tool result). |
502 | Tool execution failed (TOOL_FAILED) |
503 | Temporarily unavailable, on our side, not a limit: the upstream data provider or the credit check is down (PROVIDER_UNAVAILABLE; nothing was charged), or idempotency is unavailable and the tool was NOT run (IDEMPOTENCY_UNAVAILABLE). Retry shortly. |
504 | The tool is still running past the 60s response ceiling and was not stopped (TOOL_TIMEOUT). With an Idempotency-Key, repeat the request to collect its answer. |
curl -X POST "https://app.seomatic.ai/api/v1/tools/list_datasets" \
-H "Authorization: Bearer $SEOMATIC_API_KEY"/tools/list_page_projectsreadThe user's own page projects (the project wizard): id, name, whether the page fields hold a {{Column}} template of their own, which dataset is attached, and whether it uses a built-in design (those c…
| Status | Description |
|---|---|
200 | { tool, result }: the tool answered. result is its output, usually a JSON string (parse it). A tool that refuses does NOT answer 200: it gets the matching 402/422/429/503 below, with its own output in result. |
400 | Invalid arguments (INVALID_ARGUMENTS; details says what) or a malformed Idempotency-Key (INVALID_IDEMPOTENCY_KEY). |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA); the plan does not include acting through the API (SCOPE_REVOKED_BY_PLAN); X-Seomatic-Client is n8n or make and the workspace has no paid plan or trial (AUTOMATION_NOT_ENTITLED); the free monthly question limit is reached (FREE_QUOTA_EXCEEDED; body carries keep_going_url and a question_pack payment link); the subscription is paused or its card was declined (BILLING_INACTIVE; body links the one step that restores it, never an upgrade); or the tool refused for credits (INSUFFICIENT_CREDITS, PAYMENT_REQUIRED; body carries the tool result); or the tool hit a plan limit (the code is the refusal code itself: PROMPT_LIMIT, CADENCE_LIMIT, MONITOR_LIMIT, PAGE_LIMIT_EXCEEDED, SEAT_LIMIT_EXCEEDED, WORKSPACE_LIMIT_EXCEEDED, PLANNER_DISABLED, AUTO_EXECUTE_DISABLED, AGENT_SKILLS_NOT_ENTITLED, PAGE_TEMPLATES_NOT_ENTITLED, HOSTED_PAGES_NOT_ENTITLED, AI_ATTRIBUTION_NOT_ENTITLED, ZAPIER_NOT_ENTITLED, BYO_KEYS_NOT_ENTITLED, INCREMENTALITY_NOT_ENTITLED, WEBHOOKS_NOT_ENTITLED; `result` holds the tool refusal). Body carries upgrade_url (and reason, for tool refusals) where an upgrade is the fix. |
403 | The plan allows it but the key creator's role in the workspace does not (FORBIDDEN_ROLE; e.g. a creator now a viewer calling an acting tool). No upgrade fixes it: an admin changes the role. |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
409 | A request with this Idempotency-Key is still running (IDEMPOTENCY_IN_PROGRESS; repeat after Retry-After to collect the result), or it ran and its answer was too large to keep (IDEMPOTENCY_RESULT_NOT_KEPT; it is not run again). |
413 | Request body over 256 KB (BODY_TOO_LARGE). Tool arguments are small JSON objects. |
422 | The tool refused: it needs a confirmation step first (NEEDS_CONFIRMATION), or it declined for another reason it states (TOOL_REFUSED); result holds its explanation. Or this Idempotency-Key was used for a different tool or arguments (IDEMPOTENCY_KEY_REUSED). |
429 | Rate limited: the per-key tool-call limit (Retry-After header set), or the tool refused for a rate cap (e.g. ARTICLE_FAILURE_CAP; body carries the tool result). |
502 | Tool execution failed (TOOL_FAILED) |
503 | Temporarily unavailable, on our side, not a limit: the upstream data provider or the credit check is down (PROVIDER_UNAVAILABLE; nothing was charged), or idempotency is unavailable and the tool was NOT run (IDEMPOTENCY_UNAVAILABLE). Retry shortly. |
504 | The tool is still running past the 60s response ceiling and was not stopped (TOOL_TIMEOUT). With an Idempotency-Key, repeat the request to collect its answer. |
curl -X POST "https://app.seomatic.ai/api/v1/tools/list_page_projects" \
-H "Authorization: Bearer $SEOMATIC_API_KEY"/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 answered. result is its output, usually a JSON string (parse it). A tool that refuses does NOT answer 200: it gets the matching 402/422/429/503 below, with its own output in result. |
400 | Invalid arguments (INVALID_ARGUMENTS; details says what) or a malformed Idempotency-Key (INVALID_IDEMPOTENCY_KEY). |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA); the plan does not include acting through the API (SCOPE_REVOKED_BY_PLAN); X-Seomatic-Client is n8n or make and the workspace has no paid plan or trial (AUTOMATION_NOT_ENTITLED); the free monthly question limit is reached (FREE_QUOTA_EXCEEDED; body carries keep_going_url and a question_pack payment link); the subscription is paused or its card was declined (BILLING_INACTIVE; body links the one step that restores it, never an upgrade); or the tool refused for credits (INSUFFICIENT_CREDITS, PAYMENT_REQUIRED; body carries the tool result); or the tool hit a plan limit (the code is the refusal code itself: PROMPT_LIMIT, CADENCE_LIMIT, MONITOR_LIMIT, PAGE_LIMIT_EXCEEDED, SEAT_LIMIT_EXCEEDED, WORKSPACE_LIMIT_EXCEEDED, PLANNER_DISABLED, AUTO_EXECUTE_DISABLED, AGENT_SKILLS_NOT_ENTITLED, PAGE_TEMPLATES_NOT_ENTITLED, HOSTED_PAGES_NOT_ENTITLED, AI_ATTRIBUTION_NOT_ENTITLED, ZAPIER_NOT_ENTITLED, BYO_KEYS_NOT_ENTITLED, INCREMENTALITY_NOT_ENTITLED, WEBHOOKS_NOT_ENTITLED; `result` holds the tool refusal). Body carries upgrade_url (and reason, for tool refusals) where an upgrade is the fix. |
403 | The plan allows it but the key creator's role in the workspace does not (FORBIDDEN_ROLE; e.g. a creator now a viewer calling an acting tool). No upgrade fixes it: an admin changes the role. |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
409 | A request with this Idempotency-Key is still running (IDEMPOTENCY_IN_PROGRESS; repeat after Retry-After to collect the result), or it ran and its answer was too large to keep (IDEMPOTENCY_RESULT_NOT_KEPT; it is not run again). |
413 | Request body over 256 KB (BODY_TOO_LARGE). Tool arguments are small JSON objects. |
422 | The tool refused: it needs a confirmation step first (NEEDS_CONFIRMATION), or it declined for another reason it states (TOOL_REFUSED); result holds its explanation. Or this Idempotency-Key was used for a different tool or arguments (IDEMPOTENCY_KEY_REUSED). |
429 | Rate limited: the per-key tool-call limit (Retry-After header set), or the tool refused for a rate cap (e.g. ARTICLE_FAILURE_CAP; body carries the tool result). |
502 | Tool execution failed (TOOL_FAILED) |
503 | Temporarily unavailable, on our side, not a limit: the upstream data provider or the credit check is down (PROVIDER_UNAVAILABLE; nothing was charged), or idempotency is unavailable and the tool was NOT run (IDEMPOTENCY_UNAVAILABLE). Retry shortly. |
504 | The tool is still running past the 60s response ceiling and was not stopped (TOOL_TIMEOUT). With an Idempotency-Key, repeat the request to collect its answer. |
curl -X POST "https://app.seomatic.ai/api/v1/tools/get_dataset_rows" \
-H "Authorization: Bearer $SEOMATIC_API_KEY" \
-H "Content-Type: application/json" \
-d '{"datasetId":"…"}'/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 answered. result is its output, usually a JSON string (parse it). A tool that refuses does NOT answer 200: it gets the matching 402/422/429/503 below, with its own output in result. |
400 | Invalid arguments (INVALID_ARGUMENTS; details says what) or a malformed Idempotency-Key (INVALID_IDEMPOTENCY_KEY). |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA); the plan does not include acting through the API (SCOPE_REVOKED_BY_PLAN); X-Seomatic-Client is n8n or make and the workspace has no paid plan or trial (AUTOMATION_NOT_ENTITLED); the free monthly question limit is reached (FREE_QUOTA_EXCEEDED; body carries keep_going_url and a question_pack payment link); the subscription is paused or its card was declined (BILLING_INACTIVE; body links the one step that restores it, never an upgrade); or the tool refused for credits (INSUFFICIENT_CREDITS, PAYMENT_REQUIRED; body carries the tool result); or the tool hit a plan limit (the code is the refusal code itself: PROMPT_LIMIT, CADENCE_LIMIT, MONITOR_LIMIT, PAGE_LIMIT_EXCEEDED, SEAT_LIMIT_EXCEEDED, WORKSPACE_LIMIT_EXCEEDED, PLANNER_DISABLED, AUTO_EXECUTE_DISABLED, AGENT_SKILLS_NOT_ENTITLED, PAGE_TEMPLATES_NOT_ENTITLED, HOSTED_PAGES_NOT_ENTITLED, AI_ATTRIBUTION_NOT_ENTITLED, ZAPIER_NOT_ENTITLED, BYO_KEYS_NOT_ENTITLED, INCREMENTALITY_NOT_ENTITLED, WEBHOOKS_NOT_ENTITLED; `result` holds the tool refusal). Body carries upgrade_url (and reason, for tool refusals) where an upgrade is the fix. |
403 | The plan allows it but the key creator's role in the workspace does not (FORBIDDEN_ROLE; e.g. a creator now a viewer calling an acting tool). No upgrade fixes it: an admin changes the role. |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
409 | A request with this Idempotency-Key is still running (IDEMPOTENCY_IN_PROGRESS; repeat after Retry-After to collect the result), or it ran and its answer was too large to keep (IDEMPOTENCY_RESULT_NOT_KEPT; it is not run again). |
413 | Request body over 256 KB (BODY_TOO_LARGE). Tool arguments are small JSON objects. |
422 | The tool refused: it needs a confirmation step first (NEEDS_CONFIRMATION), or it declined for another reason it states (TOOL_REFUSED); result holds its explanation. Or this Idempotency-Key was used for a different tool or arguments (IDEMPOTENCY_KEY_REUSED). |
429 | Rate limited: the per-key tool-call limit (Retry-After header set), or the tool refused for a rate cap (e.g. ARTICLE_FAILURE_CAP; body carries the tool result). |
502 | Tool execution failed (TOOL_FAILED) |
503 | Temporarily unavailable, on our side, not a limit: the upstream data provider or the credit check is down (PROVIDER_UNAVAILABLE; nothing was charged), or idempotency is unavailable and the tool was NOT run (IDEMPOTENCY_UNAVAILABLE). Retry shortly. |
504 | The tool is still running past the 60s response ceiling and was not stopped (TOOL_TIMEOUT). With an Idempotency-Key, repeat the request to collect its answer. |
curl -X POST "https://app.seomatic.ai/api/v1/tools/upload_csv" \
-H "Authorization: Bearer $SEOMATIC_API_KEY" \
-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 answered. result is its output, usually a JSON string (parse it). A tool that refuses does NOT answer 200: it gets the matching 402/422/429/503 below, with its own output in result. |
400 | Invalid arguments (INVALID_ARGUMENTS; details says what) or a malformed Idempotency-Key (INVALID_IDEMPOTENCY_KEY). |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA); the plan does not include acting through the API (SCOPE_REVOKED_BY_PLAN); X-Seomatic-Client is n8n or make and the workspace has no paid plan or trial (AUTOMATION_NOT_ENTITLED); the free monthly question limit is reached (FREE_QUOTA_EXCEEDED; body carries keep_going_url and a question_pack payment link); the subscription is paused or its card was declined (BILLING_INACTIVE; body links the one step that restores it, never an upgrade); or the tool refused for credits (INSUFFICIENT_CREDITS, PAYMENT_REQUIRED; body carries the tool result); or the tool hit a plan limit (the code is the refusal code itself: PROMPT_LIMIT, CADENCE_LIMIT, MONITOR_LIMIT, PAGE_LIMIT_EXCEEDED, SEAT_LIMIT_EXCEEDED, WORKSPACE_LIMIT_EXCEEDED, PLANNER_DISABLED, AUTO_EXECUTE_DISABLED, AGENT_SKILLS_NOT_ENTITLED, PAGE_TEMPLATES_NOT_ENTITLED, HOSTED_PAGES_NOT_ENTITLED, AI_ATTRIBUTION_NOT_ENTITLED, ZAPIER_NOT_ENTITLED, BYO_KEYS_NOT_ENTITLED, INCREMENTALITY_NOT_ENTITLED, WEBHOOKS_NOT_ENTITLED; `result` holds the tool refusal). Body carries upgrade_url (and reason, for tool refusals) where an upgrade is the fix. |
403 | The plan allows it but the key creator's role in the workspace does not (FORBIDDEN_ROLE; e.g. a creator now a viewer calling an acting tool). No upgrade fixes it: an admin changes the role. |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
409 | A request with this Idempotency-Key is still running (IDEMPOTENCY_IN_PROGRESS; repeat after Retry-After to collect the result), or it ran and its answer was too large to keep (IDEMPOTENCY_RESULT_NOT_KEPT; it is not run again). |
413 | Request body over 256 KB (BODY_TOO_LARGE). Tool arguments are small JSON objects. |
422 | The tool refused: it needs a confirmation step first (NEEDS_CONFIRMATION), or it declined for another reason it states (TOOL_REFUSED); result holds its explanation. Or this Idempotency-Key was used for a different tool or arguments (IDEMPOTENCY_KEY_REUSED). |
429 | Rate limited: the per-key tool-call limit (Retry-After header set), or the tool refused for a rate cap (e.g. ARTICLE_FAILURE_CAP; body carries the tool result). |
502 | Tool execution failed (TOOL_FAILED) |
503 | Temporarily unavailable, on our side, not a limit: the upstream data provider or the credit check is down (PROVIDER_UNAVAILABLE; nothing was charged), or idempotency is unavailable and the tool was NOT run (IDEMPOTENCY_UNAVAILABLE). Retry shortly. |
504 | The tool is still running past the 60s response ceiling and was not stopped (TOOL_TIMEOUT). With an Idempotency-Key, repeat the request to collect its answer. |
curl -X POST "https://app.seomatic.ai/api/v1/tools/import_attachment_as_dataset" \
-H "Authorization: Bearer $SEOMATIC_API_KEY" \
-H "Content-Type: application/json" \
-d '{"attachmentId":"00000000-0000-0000-0000-000000000000"}'/tools/list_page_templatesreadThe built-in page templates of the project wizard (read-only reference). Returns each template's id, what it's for, the dataset columns it requires, and its AI cost per page. They cannot be used from…
| Status | Description |
|---|---|
200 | { tool, result }: the tool answered. result is its output, usually a JSON string (parse it). A tool that refuses does NOT answer 200: it gets the matching 402/422/429/503 below, with its own output in result. |
400 | Invalid arguments (INVALID_ARGUMENTS; details says what) or a malformed Idempotency-Key (INVALID_IDEMPOTENCY_KEY). |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA); the plan does not include acting through the API (SCOPE_REVOKED_BY_PLAN); X-Seomatic-Client is n8n or make and the workspace has no paid plan or trial (AUTOMATION_NOT_ENTITLED); the free monthly question limit is reached (FREE_QUOTA_EXCEEDED; body carries keep_going_url and a question_pack payment link); the subscription is paused or its card was declined (BILLING_INACTIVE; body links the one step that restores it, never an upgrade); or the tool refused for credits (INSUFFICIENT_CREDITS, PAYMENT_REQUIRED; body carries the tool result); or the tool hit a plan limit (the code is the refusal code itself: PROMPT_LIMIT, CADENCE_LIMIT, MONITOR_LIMIT, PAGE_LIMIT_EXCEEDED, SEAT_LIMIT_EXCEEDED, WORKSPACE_LIMIT_EXCEEDED, PLANNER_DISABLED, AUTO_EXECUTE_DISABLED, AGENT_SKILLS_NOT_ENTITLED, PAGE_TEMPLATES_NOT_ENTITLED, HOSTED_PAGES_NOT_ENTITLED, AI_ATTRIBUTION_NOT_ENTITLED, ZAPIER_NOT_ENTITLED, BYO_KEYS_NOT_ENTITLED, INCREMENTALITY_NOT_ENTITLED, WEBHOOKS_NOT_ENTITLED; `result` holds the tool refusal). Body carries upgrade_url (and reason, for tool refusals) where an upgrade is the fix. |
403 | The plan allows it but the key creator's role in the workspace does not (FORBIDDEN_ROLE; e.g. a creator now a viewer calling an acting tool). No upgrade fixes it: an admin changes the role. |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
409 | A request with this Idempotency-Key is still running (IDEMPOTENCY_IN_PROGRESS; repeat after Retry-After to collect the result), or it ran and its answer was too large to keep (IDEMPOTENCY_RESULT_NOT_KEPT; it is not run again). |
413 | Request body over 256 KB (BODY_TOO_LARGE). Tool arguments are small JSON objects. |
422 | The tool refused: it needs a confirmation step first (NEEDS_CONFIRMATION), or it declined for another reason it states (TOOL_REFUSED); result holds its explanation. Or this Idempotency-Key was used for a different tool or arguments (IDEMPOTENCY_KEY_REUSED). |
429 | Rate limited: the per-key tool-call limit (Retry-After header set), or the tool refused for a rate cap (e.g. ARTICLE_FAILURE_CAP; body carries the tool result). |
502 | Tool execution failed (TOOL_FAILED) |
503 | Temporarily unavailable, on our side, not a limit: the upstream data provider or the credit check is down (PROVIDER_UNAVAILABLE; nothing was charged), or idempotency is unavailable and the tool was NOT run (IDEMPOTENCY_UNAVAILABLE). Retry shortly. |
504 | The tool is still running past the 60s response ceiling and was not stopped (TOOL_TIMEOUT). With an Idempotency-Key, repeat the request to collect its answer. |
curl -X POST "https://app.seomatic.ai/api/v1/tools/list_page_templates" \
-H "Authorization: Bearer $SEOMATIC_API_KEY"/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 answered. result is its output, usually a JSON string (parse it). A tool that refuses does NOT answer 200: it gets the matching 402/422/429/503 below, with its own output in result. |
400 | Invalid arguments (INVALID_ARGUMENTS; details says what) or a malformed Idempotency-Key (INVALID_IDEMPOTENCY_KEY). |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA); the plan does not include acting through the API (SCOPE_REVOKED_BY_PLAN); X-Seomatic-Client is n8n or make and the workspace has no paid plan or trial (AUTOMATION_NOT_ENTITLED); the free monthly question limit is reached (FREE_QUOTA_EXCEEDED; body carries keep_going_url and a question_pack payment link); the subscription is paused or its card was declined (BILLING_INACTIVE; body links the one step that restores it, never an upgrade); or the tool refused for credits (INSUFFICIENT_CREDITS, PAYMENT_REQUIRED; body carries the tool result); or the tool hit a plan limit (the code is the refusal code itself: PROMPT_LIMIT, CADENCE_LIMIT, MONITOR_LIMIT, PAGE_LIMIT_EXCEEDED, SEAT_LIMIT_EXCEEDED, WORKSPACE_LIMIT_EXCEEDED, PLANNER_DISABLED, AUTO_EXECUTE_DISABLED, AGENT_SKILLS_NOT_ENTITLED, PAGE_TEMPLATES_NOT_ENTITLED, HOSTED_PAGES_NOT_ENTITLED, AI_ATTRIBUTION_NOT_ENTITLED, ZAPIER_NOT_ENTITLED, BYO_KEYS_NOT_ENTITLED, INCREMENTALITY_NOT_ENTITLED, WEBHOOKS_NOT_ENTITLED; `result` holds the tool refusal). Body carries upgrade_url (and reason, for tool refusals) where an upgrade is the fix. |
403 | The plan allows it but the key creator's role in the workspace does not (FORBIDDEN_ROLE; e.g. a creator now a viewer calling an acting tool). No upgrade fixes it: an admin changes the role. |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
409 | A request with this Idempotency-Key is still running (IDEMPOTENCY_IN_PROGRESS; repeat after Retry-After to collect the result), or it ran and its answer was too large to keep (IDEMPOTENCY_RESULT_NOT_KEPT; it is not run again). |
413 | Request body over 256 KB (BODY_TOO_LARGE). Tool arguments are small JSON objects. |
422 | The tool refused: it needs a confirmation step first (NEEDS_CONFIRMATION), or it declined for another reason it states (TOOL_REFUSED); result holds its explanation. Or this Idempotency-Key was used for a different tool or arguments (IDEMPOTENCY_KEY_REUSED). |
429 | Rate limited: the per-key tool-call limit (Retry-After header set), or the tool refused for a rate cap (e.g. ARTICLE_FAILURE_CAP; body carries the tool result). |
502 | Tool execution failed (TOOL_FAILED) |
503 | Temporarily unavailable, on our side, not a limit: the upstream data provider or the credit check is down (PROVIDER_UNAVAILABLE; nothing was charged), or idempotency is unavailable and the tool was NOT run (IDEMPOTENCY_UNAVAILABLE). Retry shortly. |
504 | The tool is still running past the 60s response ceiling and was not stopped (TOOL_TIMEOUT). With an Idempotency-Key, repeat the request to collect its answer. |
curl -X POST "https://app.seomatic.ai/api/v1/tools/get_page_template" \
-H "Authorization: Bearer $SEOMATIC_API_KEY" \
-H "Content-Type: application/json" \
-d '{"templateId":"…"}'Crawl, analyze, audit, and inventory the site itself.
/page-auditScore one public page for AI/LLM answerability.
Fetches a public URL and scores how answerable it is for AI engines. The key-authed lane the WordPress AI-visibility plugin calls. The URL must be publicly reachable; private/internal addresses are ssrf-rejected.
| 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 $SEOMATIC_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url":"https://example.com/page"}'/link-densityStore the site's internal-linking health reading.
A coarse internal-linking-health snapshot: how many posts were sampled and how many internal links they contain. One row per workspace, latest wins. Counts only, never content or URLs.
| 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 $SEOMATIC_API_KEY"/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 $SEOMATIC_API_KEY"/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/$TASK_ID/ack" \
-H "Authorization: Bearer $SEOMATIC_API_KEY"/tools/analyze_page_seoreadAnalyze a webpage for SEO issues and return an SEO score (0-100) with issues ranked by impact: indexability first (HTTP errors, noindex in the meta tag or X-Robots-Tag header, a canonical pointing el…
| Name | Type | Required | Description |
|---|---|---|---|
url | string (uri) | yes | The full URL of the page to analyze |
| Status | Description |
|---|---|
200 | { tool, result }: the tool answered. result is its output, usually a JSON string (parse it). A tool that refuses does NOT answer 200: it gets the matching 402/422/429/503 below, with its own output in result. |
400 | Invalid arguments (INVALID_ARGUMENTS; details says what) or a malformed Idempotency-Key (INVALID_IDEMPOTENCY_KEY). |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA); the plan does not include acting through the API (SCOPE_REVOKED_BY_PLAN); X-Seomatic-Client is n8n or make and the workspace has no paid plan or trial (AUTOMATION_NOT_ENTITLED); the free monthly question limit is reached (FREE_QUOTA_EXCEEDED; body carries keep_going_url and a question_pack payment link); the subscription is paused or its card was declined (BILLING_INACTIVE; body links the one step that restores it, never an upgrade); or the tool refused for credits (INSUFFICIENT_CREDITS, PAYMENT_REQUIRED; body carries the tool result); or the tool hit a plan limit (the code is the refusal code itself: PROMPT_LIMIT, CADENCE_LIMIT, MONITOR_LIMIT, PAGE_LIMIT_EXCEEDED, SEAT_LIMIT_EXCEEDED, WORKSPACE_LIMIT_EXCEEDED, PLANNER_DISABLED, AUTO_EXECUTE_DISABLED, AGENT_SKILLS_NOT_ENTITLED, PAGE_TEMPLATES_NOT_ENTITLED, HOSTED_PAGES_NOT_ENTITLED, AI_ATTRIBUTION_NOT_ENTITLED, ZAPIER_NOT_ENTITLED, BYO_KEYS_NOT_ENTITLED, INCREMENTALITY_NOT_ENTITLED, WEBHOOKS_NOT_ENTITLED; `result` holds the tool refusal). Body carries upgrade_url (and reason, for tool refusals) where an upgrade is the fix. |
403 | The plan allows it but the key creator's role in the workspace does not (FORBIDDEN_ROLE; e.g. a creator now a viewer calling an acting tool). No upgrade fixes it: an admin changes the role. |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
409 | A request with this Idempotency-Key is still running (IDEMPOTENCY_IN_PROGRESS; repeat after Retry-After to collect the result), or it ran and its answer was too large to keep (IDEMPOTENCY_RESULT_NOT_KEPT; it is not run again). |
413 | Request body over 256 KB (BODY_TOO_LARGE). Tool arguments are small JSON objects. |
422 | The tool refused: it needs a confirmation step first (NEEDS_CONFIRMATION), or it declined for another reason it states (TOOL_REFUSED); result holds its explanation. Or this Idempotency-Key was used for a different tool or arguments (IDEMPOTENCY_KEY_REUSED). |
429 | Rate limited: the per-key tool-call limit (Retry-After header set), or the tool refused for a rate cap (e.g. ARTICLE_FAILURE_CAP; body carries the tool result). |
502 | Tool execution failed (TOOL_FAILED) |
503 | Temporarily unavailable, on our side, not a limit: the upstream data provider or the credit check is down (PROVIDER_UNAVAILABLE; nothing was charged), or idempotency is unavailable and the tool was NOT run (IDEMPOTENCY_UNAVAILABLE). Retry shortly. |
504 | The tool is still running past the 60s response ceiling and was not stopped (TOOL_TIMEOUT). With an Idempotency-Key, repeat the request to collect its answer. |
curl -X POST "https://app.seomatic.ai/api/v1/tools/analyze_page_seo" \
-H "Authorization: Bearer $SEOMATIC_API_KEY" \
-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 answered. result is its output, usually a JSON string (parse it). A tool that refuses does NOT answer 200: it gets the matching 402/422/429/503 below, with its own output in result. |
400 | Invalid arguments (INVALID_ARGUMENTS; details says what) or a malformed Idempotency-Key (INVALID_IDEMPOTENCY_KEY). |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA); the plan does not include acting through the API (SCOPE_REVOKED_BY_PLAN); X-Seomatic-Client is n8n or make and the workspace has no paid plan or trial (AUTOMATION_NOT_ENTITLED); the free monthly question limit is reached (FREE_QUOTA_EXCEEDED; body carries keep_going_url and a question_pack payment link); the subscription is paused or its card was declined (BILLING_INACTIVE; body links the one step that restores it, never an upgrade); or the tool refused for credits (INSUFFICIENT_CREDITS, PAYMENT_REQUIRED; body carries the tool result); or the tool hit a plan limit (the code is the refusal code itself: PROMPT_LIMIT, CADENCE_LIMIT, MONITOR_LIMIT, PAGE_LIMIT_EXCEEDED, SEAT_LIMIT_EXCEEDED, WORKSPACE_LIMIT_EXCEEDED, PLANNER_DISABLED, AUTO_EXECUTE_DISABLED, AGENT_SKILLS_NOT_ENTITLED, PAGE_TEMPLATES_NOT_ENTITLED, HOSTED_PAGES_NOT_ENTITLED, AI_ATTRIBUTION_NOT_ENTITLED, ZAPIER_NOT_ENTITLED, BYO_KEYS_NOT_ENTITLED, INCREMENTALITY_NOT_ENTITLED, WEBHOOKS_NOT_ENTITLED; `result` holds the tool refusal). Body carries upgrade_url (and reason, for tool refusals) where an upgrade is the fix. |
403 | The plan allows it but the key creator's role in the workspace does not (FORBIDDEN_ROLE; e.g. a creator now a viewer calling an acting tool). No upgrade fixes it: an admin changes the role. |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
409 | A request with this Idempotency-Key is still running (IDEMPOTENCY_IN_PROGRESS; repeat after Retry-After to collect the result), or it ran and its answer was too large to keep (IDEMPOTENCY_RESULT_NOT_KEPT; it is not run again). |
413 | Request body over 256 KB (BODY_TOO_LARGE). Tool arguments are small JSON objects. |
422 | The tool refused: it needs a confirmation step first (NEEDS_CONFIRMATION), or it declined for another reason it states (TOOL_REFUSED); result holds its explanation. Or this Idempotency-Key was used for a different tool or arguments (IDEMPOTENCY_KEY_REUSED). |
429 | Rate limited: the per-key tool-call limit (Retry-After header set), or the tool refused for a rate cap (e.g. ARTICLE_FAILURE_CAP; body carries the tool result). |
502 | Tool execution failed (TOOL_FAILED) |
503 | Temporarily unavailable, on our side, not a limit: the upstream data provider or the credit check is down (PROVIDER_UNAVAILABLE; nothing was charged), or idempotency is unavailable and the tool was NOT run (IDEMPOTENCY_UNAVAILABLE). Retry shortly. |
504 | The tool is still running past the 60s response ceiling and was not stopped (TOOL_TIMEOUT). With an Idempotency-Key, repeat the request to collect its answer. |
curl -X POST "https://app.seomatic.ai/api/v1/tools/crawl_page" \
-H "Authorization: Bearer $SEOMATIC_API_KEY" \
-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 answered. result is its output, usually a JSON string (parse it). A tool that refuses does NOT answer 200: it gets the matching 402/422/429/503 below, with its own output in result. |
400 | Invalid arguments (INVALID_ARGUMENTS; details says what) or a malformed Idempotency-Key (INVALID_IDEMPOTENCY_KEY). |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA); the plan does not include acting through the API (SCOPE_REVOKED_BY_PLAN); X-Seomatic-Client is n8n or make and the workspace has no paid plan or trial (AUTOMATION_NOT_ENTITLED); the free monthly question limit is reached (FREE_QUOTA_EXCEEDED; body carries keep_going_url and a question_pack payment link); the subscription is paused or its card was declined (BILLING_INACTIVE; body links the one step that restores it, never an upgrade); or the tool refused for credits (INSUFFICIENT_CREDITS, PAYMENT_REQUIRED; body carries the tool result); or the tool hit a plan limit (the code is the refusal code itself: PROMPT_LIMIT, CADENCE_LIMIT, MONITOR_LIMIT, PAGE_LIMIT_EXCEEDED, SEAT_LIMIT_EXCEEDED, WORKSPACE_LIMIT_EXCEEDED, PLANNER_DISABLED, AUTO_EXECUTE_DISABLED, AGENT_SKILLS_NOT_ENTITLED, PAGE_TEMPLATES_NOT_ENTITLED, HOSTED_PAGES_NOT_ENTITLED, AI_ATTRIBUTION_NOT_ENTITLED, ZAPIER_NOT_ENTITLED, BYO_KEYS_NOT_ENTITLED, INCREMENTALITY_NOT_ENTITLED, WEBHOOKS_NOT_ENTITLED; `result` holds the tool refusal). Body carries upgrade_url (and reason, for tool refusals) where an upgrade is the fix. |
403 | The plan allows it but the key creator's role in the workspace does not (FORBIDDEN_ROLE; e.g. a creator now a viewer calling an acting tool). No upgrade fixes it: an admin changes the role. |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
409 | A request with this Idempotency-Key is still running (IDEMPOTENCY_IN_PROGRESS; repeat after Retry-After to collect the result), or it ran and its answer was too large to keep (IDEMPOTENCY_RESULT_NOT_KEPT; it is not run again). |
413 | Request body over 256 KB (BODY_TOO_LARGE). Tool arguments are small JSON objects. |
422 | The tool refused: it needs a confirmation step first (NEEDS_CONFIRMATION), or it declined for another reason it states (TOOL_REFUSED); result holds its explanation. Or this Idempotency-Key was used for a different tool or arguments (IDEMPOTENCY_KEY_REUSED). |
429 | Rate limited: the per-key tool-call limit (Retry-After header set), or the tool refused for a rate cap (e.g. ARTICLE_FAILURE_CAP; body carries the tool result). |
502 | Tool execution failed (TOOL_FAILED) |
503 | Temporarily unavailable, on our side, not a limit: the upstream data provider or the credit check is down (PROVIDER_UNAVAILABLE; nothing was charged), or idempotency is unavailable and the tool was NOT run (IDEMPOTENCY_UNAVAILABLE). Retry shortly. |
504 | The tool is still running past the 60s response ceiling and was not stopped (TOOL_TIMEOUT). With an Idempotency-Key, repeat the request to collect its answer. |
curl -X POST "https://app.seomatic.ai/api/v1/tools/get_site_inventory" \
-H "Authorization: Bearer $SEOMATIC_API_KEY"/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 answered. result is its output, usually a JSON string (parse it). A tool that refuses does NOT answer 200: it gets the matching 402/422/429/503 below, with its own output in result. |
400 | Invalid arguments (INVALID_ARGUMENTS; details says what) or a malformed Idempotency-Key (INVALID_IDEMPOTENCY_KEY). |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA); the plan does not include acting through the API (SCOPE_REVOKED_BY_PLAN); X-Seomatic-Client is n8n or make and the workspace has no paid plan or trial (AUTOMATION_NOT_ENTITLED); the free monthly question limit is reached (FREE_QUOTA_EXCEEDED; body carries keep_going_url and a question_pack payment link); the subscription is paused or its card was declined (BILLING_INACTIVE; body links the one step that restores it, never an upgrade); or the tool refused for credits (INSUFFICIENT_CREDITS, PAYMENT_REQUIRED; body carries the tool result); or the tool hit a plan limit (the code is the refusal code itself: PROMPT_LIMIT, CADENCE_LIMIT, MONITOR_LIMIT, PAGE_LIMIT_EXCEEDED, SEAT_LIMIT_EXCEEDED, WORKSPACE_LIMIT_EXCEEDED, PLANNER_DISABLED, AUTO_EXECUTE_DISABLED, AGENT_SKILLS_NOT_ENTITLED, PAGE_TEMPLATES_NOT_ENTITLED, HOSTED_PAGES_NOT_ENTITLED, AI_ATTRIBUTION_NOT_ENTITLED, ZAPIER_NOT_ENTITLED, BYO_KEYS_NOT_ENTITLED, INCREMENTALITY_NOT_ENTITLED, WEBHOOKS_NOT_ENTITLED; `result` holds the tool refusal). Body carries upgrade_url (and reason, for tool refusals) where an upgrade is the fix. |
403 | The plan allows it but the key creator's role in the workspace does not (FORBIDDEN_ROLE; e.g. a creator now a viewer calling an acting tool). No upgrade fixes it: an admin changes the role. |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
409 | A request with this Idempotency-Key is still running (IDEMPOTENCY_IN_PROGRESS; repeat after Retry-After to collect the result), or it ran and its answer was too large to keep (IDEMPOTENCY_RESULT_NOT_KEPT; it is not run again). |
413 | Request body over 256 KB (BODY_TOO_LARGE). Tool arguments are small JSON objects. |
422 | The tool refused: it needs a confirmation step first (NEEDS_CONFIRMATION), or it declined for another reason it states (TOOL_REFUSED); result holds its explanation. Or this Idempotency-Key was used for a different tool or arguments (IDEMPOTENCY_KEY_REUSED). |
429 | Rate limited: the per-key tool-call limit (Retry-After header set), or the tool refused for a rate cap (e.g. ARTICLE_FAILURE_CAP; body carries the tool result). |
502 | Tool execution failed (TOOL_FAILED) |
503 | Temporarily unavailable, on our side, not a limit: the upstream data provider or the credit check is down (PROVIDER_UNAVAILABLE; nothing was charged), or idempotency is unavailable and the tool was NOT run (IDEMPOTENCY_UNAVAILABLE). Retry shortly. |
504 | The tool is still running past the 60s response ceiling and was not stopped (TOOL_TIMEOUT). With an Idempotency-Key, repeat the request to collect its answer. |
curl -X POST "https://app.seomatic.ai/api/v1/tools/site_audit" \
-H "Authorization: Bearer $SEOMATIC_API_KEY"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 $SEOMATIC_API_KEY"/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". |
caller_ref | string | no | Optional opaque tag for YOUR end customer (e.g. "shop:1234"), stored on the article. For approved reseller accounts (contact support), the daily failed-article and cancel limits apply per tag under an account-wide ceiling, so one customer cannot lock out the others; on every other account the account-wide limits apply as without a tag. Never send secrets or personal data. |
| 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, or too many failed articles in 24 hours (ARTICLE_FAILURE_CAP; scope "caller" = this caller_ref only (reseller accounts), "org" = the whole account). Nothing was consumed. |
curl -X POST "https://app.seomatic.ai/api/v1/articles" \
-H "Authorization: Bearer $SEOMATIC_API_KEY" \
-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|canceled, title, markdown, html, wordCount, aiSearchScore, contentScore, featuredImageUrl, errorMessage } } |
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/$ARTICLE_ID" \
-H "Authorization: Bearer $SEOMATIC_API_KEY"/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/$ARTICLE_ID" \
-H "Authorization: Bearer $SEOMATIC_API_KEY" \
-H "Content-Type: application/json" \
-d '{"title":"New title"}'/articles/{articleId}/cancelCancel a queued or generating article and get its prepaid unit back. Generation stops at its next step. Idempotent: repeating it answers 200 with already_canceled and refunds nothing. A finished or failed article answers 409 and nothing is refunded (a failed article was already refunded).
| Name | In | Type | Required | Description |
|---|---|---|---|---|
articleId | path | string (uuid) | yes |
| Status | Description |
|---|---|
200 | { id, status: "canceled", refunded } (plus already_canceled: true on a repeat, with refunded: false) |
401 | Missing or invalid API key |
404 | Article not found (NOT_FOUND) |
409 | Already settled (ARTICLE_ALREADY_READY or ARTICLE_ALREADY_FAILED); nothing refunded. |
429 | Rate limited, or too many canceled articles in 24 hours (ARTICLE_CANCEL_LIMIT): the article keeps generating and is delivered as usual. |
curl -X POST "https://app.seomatic.ai/api/v1/articles/$ARTICLE_ID/cancel" \
-H "Authorization: Bearer $SEOMATIC_API_KEY"/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 $SEOMATIC_API_KEY"/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 $SEOMATIC_API_KEY" \
-H "Content-Type: application/json" \
-d '{"spt_token":"…"}'/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 $SEOMATIC_API_KEY"/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 answered. result is its output, usually a JSON string (parse it). A tool that refuses does NOT answer 200: it gets the matching 402/422/429/503 below, with its own output in result. |
400 | Invalid arguments (INVALID_ARGUMENTS; details says what) or a malformed Idempotency-Key (INVALID_IDEMPOTENCY_KEY). |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA); the plan does not include acting through the API (SCOPE_REVOKED_BY_PLAN); X-Seomatic-Client is n8n or make and the workspace has no paid plan or trial (AUTOMATION_NOT_ENTITLED); the free monthly question limit is reached (FREE_QUOTA_EXCEEDED; body carries keep_going_url and a question_pack payment link); the subscription is paused or its card was declined (BILLING_INACTIVE; body links the one step that restores it, never an upgrade); or the tool refused for credits (INSUFFICIENT_CREDITS, PAYMENT_REQUIRED; body carries the tool result); or the tool hit a plan limit (the code is the refusal code itself: PROMPT_LIMIT, CADENCE_LIMIT, MONITOR_LIMIT, PAGE_LIMIT_EXCEEDED, SEAT_LIMIT_EXCEEDED, WORKSPACE_LIMIT_EXCEEDED, PLANNER_DISABLED, AUTO_EXECUTE_DISABLED, AGENT_SKILLS_NOT_ENTITLED, PAGE_TEMPLATES_NOT_ENTITLED, HOSTED_PAGES_NOT_ENTITLED, AI_ATTRIBUTION_NOT_ENTITLED, ZAPIER_NOT_ENTITLED, BYO_KEYS_NOT_ENTITLED, INCREMENTALITY_NOT_ENTITLED, WEBHOOKS_NOT_ENTITLED; `result` holds the tool refusal). Body carries upgrade_url (and reason, for tool refusals) where an upgrade is the fix. |
403 | The plan allows it but the key creator's role in the workspace does not (FORBIDDEN_ROLE; e.g. a creator now a viewer calling an acting tool). No upgrade fixes it: an admin changes the role. |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
409 | A request with this Idempotency-Key is still running (IDEMPOTENCY_IN_PROGRESS; repeat after Retry-After to collect the result), or it ran and its answer was too large to keep (IDEMPOTENCY_RESULT_NOT_KEPT; it is not run again). |
413 | Request body over 256 KB (BODY_TOO_LARGE). Tool arguments are small JSON objects. |
422 | The tool refused: it needs a confirmation step first (NEEDS_CONFIRMATION), or it declined for another reason it states (TOOL_REFUSED); result holds its explanation. Or this Idempotency-Key was used for a different tool or arguments (IDEMPOTENCY_KEY_REUSED). |
429 | Rate limited: the per-key tool-call limit (Retry-After header set), or the tool refused for a rate cap (e.g. ARTICLE_FAILURE_CAP; body carries the tool result). |
502 | Tool execution failed (TOOL_FAILED) |
503 | Temporarily unavailable, on our side, not a limit: the upstream data provider or the credit check is down (PROVIDER_UNAVAILABLE; nothing was charged), or idempotency is unavailable and the tool was NOT run (IDEMPOTENCY_UNAVAILABLE). Retry shortly. |
504 | The tool is still running past the 60s response ceiling and was not stopped (TOOL_TIMEOUT). With an Idempotency-Key, repeat the request to collect its answer. |
curl -X POST "https://app.seomatic.ai/api/v1/tools/generate_article" \
-H "Authorization: Bearer $SEOMATIC_API_KEY" \
-H "Content-Type: application/json" \
-d '{"topic":"…"}'/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 answered. result is its output, usually a JSON string (parse it). A tool that refuses does NOT answer 200: it gets the matching 402/422/429/503 below, with its own output in result. |
400 | Invalid arguments (INVALID_ARGUMENTS; details says what) or a malformed Idempotency-Key (INVALID_IDEMPOTENCY_KEY). |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA); the plan does not include acting through the API (SCOPE_REVOKED_BY_PLAN); X-Seomatic-Client is n8n or make and the workspace has no paid plan or trial (AUTOMATION_NOT_ENTITLED); the free monthly question limit is reached (FREE_QUOTA_EXCEEDED; body carries keep_going_url and a question_pack payment link); the subscription is paused or its card was declined (BILLING_INACTIVE; body links the one step that restores it, never an upgrade); or the tool refused for credits (INSUFFICIENT_CREDITS, PAYMENT_REQUIRED; body carries the tool result); or the tool hit a plan limit (the code is the refusal code itself: PROMPT_LIMIT, CADENCE_LIMIT, MONITOR_LIMIT, PAGE_LIMIT_EXCEEDED, SEAT_LIMIT_EXCEEDED, WORKSPACE_LIMIT_EXCEEDED, PLANNER_DISABLED, AUTO_EXECUTE_DISABLED, AGENT_SKILLS_NOT_ENTITLED, PAGE_TEMPLATES_NOT_ENTITLED, HOSTED_PAGES_NOT_ENTITLED, AI_ATTRIBUTION_NOT_ENTITLED, ZAPIER_NOT_ENTITLED, BYO_KEYS_NOT_ENTITLED, INCREMENTALITY_NOT_ENTITLED, WEBHOOKS_NOT_ENTITLED; `result` holds the tool refusal). Body carries upgrade_url (and reason, for tool refusals) where an upgrade is the fix. |
403 | The plan allows it but the key creator's role in the workspace does not (FORBIDDEN_ROLE; e.g. a creator now a viewer calling an acting tool). No upgrade fixes it: an admin changes the role. |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
409 | A request with this Idempotency-Key is still running (IDEMPOTENCY_IN_PROGRESS; repeat after Retry-After to collect the result), or it ran and its answer was too large to keep (IDEMPOTENCY_RESULT_NOT_KEPT; it is not run again). |
413 | Request body over 256 KB (BODY_TOO_LARGE). Tool arguments are small JSON objects. |
422 | The tool refused: it needs a confirmation step first (NEEDS_CONFIRMATION), or it declined for another reason it states (TOOL_REFUSED); result holds its explanation. Or this Idempotency-Key was used for a different tool or arguments (IDEMPOTENCY_KEY_REUSED). |
429 | Rate limited: the per-key tool-call limit (Retry-After header set), or the tool refused for a rate cap (e.g. ARTICLE_FAILURE_CAP; body carries the tool result). |
502 | Tool execution failed (TOOL_FAILED) |
503 | Temporarily unavailable, on our side, not a limit: the upstream data provider or the credit check is down (PROVIDER_UNAVAILABLE; nothing was charged), or idempotency is unavailable and the tool was NOT run (IDEMPOTENCY_UNAVAILABLE). Retry shortly. |
504 | The tool is still running past the 60s response ceiling and was not stopped (TOOL_TIMEOUT). With an Idempotency-Key, repeat the request to collect its answer. |
curl -X POST "https://app.seomatic.ai/api/v1/tools/get_article" \
-H "Authorization: Bearer $SEOMATIC_API_KEY"/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 answered. result is its output, usually a JSON string (parse it). A tool that refuses does NOT answer 200: it gets the matching 402/422/429/503 below, with its own output in result. |
400 | Invalid arguments (INVALID_ARGUMENTS; details says what) or a malformed Idempotency-Key (INVALID_IDEMPOTENCY_KEY). |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA); the plan does not include acting through the API (SCOPE_REVOKED_BY_PLAN); X-Seomatic-Client is n8n or make and the workspace has no paid plan or trial (AUTOMATION_NOT_ENTITLED); the free monthly question limit is reached (FREE_QUOTA_EXCEEDED; body carries keep_going_url and a question_pack payment link); the subscription is paused or its card was declined (BILLING_INACTIVE; body links the one step that restores it, never an upgrade); or the tool refused for credits (INSUFFICIENT_CREDITS, PAYMENT_REQUIRED; body carries the tool result); or the tool hit a plan limit (the code is the refusal code itself: PROMPT_LIMIT, CADENCE_LIMIT, MONITOR_LIMIT, PAGE_LIMIT_EXCEEDED, SEAT_LIMIT_EXCEEDED, WORKSPACE_LIMIT_EXCEEDED, PLANNER_DISABLED, AUTO_EXECUTE_DISABLED, AGENT_SKILLS_NOT_ENTITLED, PAGE_TEMPLATES_NOT_ENTITLED, HOSTED_PAGES_NOT_ENTITLED, AI_ATTRIBUTION_NOT_ENTITLED, ZAPIER_NOT_ENTITLED, BYO_KEYS_NOT_ENTITLED, INCREMENTALITY_NOT_ENTITLED, WEBHOOKS_NOT_ENTITLED; `result` holds the tool refusal). Body carries upgrade_url (and reason, for tool refusals) where an upgrade is the fix. |
403 | The plan allows it but the key creator's role in the workspace does not (FORBIDDEN_ROLE; e.g. a creator now a viewer calling an acting tool). No upgrade fixes it: an admin changes the role. |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
409 | A request with this Idempotency-Key is still running (IDEMPOTENCY_IN_PROGRESS; repeat after Retry-After to collect the result), or it ran and its answer was too large to keep (IDEMPOTENCY_RESULT_NOT_KEPT; it is not run again). |
413 | Request body over 256 KB (BODY_TOO_LARGE). Tool arguments are small JSON objects. |
422 | The tool refused: it needs a confirmation step first (NEEDS_CONFIRMATION), or it declined for another reason it states (TOOL_REFUSED); result holds its explanation. Or this Idempotency-Key was used for a different tool or arguments (IDEMPOTENCY_KEY_REUSED). |
429 | Rate limited: the per-key tool-call limit (Retry-After header set), or the tool refused for a rate cap (e.g. ARTICLE_FAILURE_CAP; body carries the tool result). |
502 | Tool execution failed (TOOL_FAILED) |
503 | Temporarily unavailable, on our side, not a limit: the upstream data provider or the credit check is down (PROVIDER_UNAVAILABLE; nothing was charged), or idempotency is unavailable and the tool was NOT run (IDEMPOTENCY_UNAVAILABLE). Retry shortly. |
504 | The tool is still running past the 60s response ceiling and was not stopped (TOOL_TIMEOUT). With an Idempotency-Key, repeat the request to collect its answer. |
curl -X POST "https://app.seomatic.ai/api/v1/tools/pay_for_articles" \
-H "Authorization: Bearer $SEOMATIC_API_KEY" \
-H "Content-Type: application/json" \
-d '{"spt_token":"…"}'/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 answered. result is its output, usually a JSON string (parse it). A tool that refuses does NOT answer 200: it gets the matching 402/422/429/503 below, with its own output in result. |
400 | Invalid arguments (INVALID_ARGUMENTS; details says what) or a malformed Idempotency-Key (INVALID_IDEMPOTENCY_KEY). |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA); the plan does not include acting through the API (SCOPE_REVOKED_BY_PLAN); X-Seomatic-Client is n8n or make and the workspace has no paid plan or trial (AUTOMATION_NOT_ENTITLED); the free monthly question limit is reached (FREE_QUOTA_EXCEEDED; body carries keep_going_url and a question_pack payment link); the subscription is paused or its card was declined (BILLING_INACTIVE; body links the one step that restores it, never an upgrade); or the tool refused for credits (INSUFFICIENT_CREDITS, PAYMENT_REQUIRED; body carries the tool result); or the tool hit a plan limit (the code is the refusal code itself: PROMPT_LIMIT, CADENCE_LIMIT, MONITOR_LIMIT, PAGE_LIMIT_EXCEEDED, SEAT_LIMIT_EXCEEDED, WORKSPACE_LIMIT_EXCEEDED, PLANNER_DISABLED, AUTO_EXECUTE_DISABLED, AGENT_SKILLS_NOT_ENTITLED, PAGE_TEMPLATES_NOT_ENTITLED, HOSTED_PAGES_NOT_ENTITLED, AI_ATTRIBUTION_NOT_ENTITLED, ZAPIER_NOT_ENTITLED, BYO_KEYS_NOT_ENTITLED, INCREMENTALITY_NOT_ENTITLED, WEBHOOKS_NOT_ENTITLED; `result` holds the tool refusal). Body carries upgrade_url (and reason, for tool refusals) where an upgrade is the fix. |
403 | The plan allows it but the key creator's role in the workspace does not (FORBIDDEN_ROLE; e.g. a creator now a viewer calling an acting tool). No upgrade fixes it: an admin changes the role. |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
409 | A request with this Idempotency-Key is still running (IDEMPOTENCY_IN_PROGRESS; repeat after Retry-After to collect the result), or it ran and its answer was too large to keep (IDEMPOTENCY_RESULT_NOT_KEPT; it is not run again). |
413 | Request body over 256 KB (BODY_TOO_LARGE). Tool arguments are small JSON objects. |
422 | The tool refused: it needs a confirmation step first (NEEDS_CONFIRMATION), or it declined for another reason it states (TOOL_REFUSED); result holds its explanation. Or this Idempotency-Key was used for a different tool or arguments (IDEMPOTENCY_KEY_REUSED). |
429 | Rate limited: the per-key tool-call limit (Retry-After header set), or the tool refused for a rate cap (e.g. ARTICLE_FAILURE_CAP; body carries the tool result). |
502 | Tool execution failed (TOOL_FAILED) |
503 | Temporarily unavailable, on our side, not a limit: the upstream data provider or the credit check is down (PROVIDER_UNAVAILABLE; nothing was charged), or idempotency is unavailable and the tool was NOT run (IDEMPOTENCY_UNAVAILABLE). Retry shortly. |
504 | The tool is still running past the 60s response ceiling and was not stopped (TOOL_TIMEOUT). With an Idempotency-Key, repeat the request to collect its answer. |
curl -X POST "https://app.seomatic.ai/api/v1/tools/get_credit_usage" \
-H "Authorization: Bearer $SEOMATIC_API_KEY"/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 answered. result is its output, usually a JSON string (parse it). A tool that refuses does NOT answer 200: it gets the matching 402/422/429/503 below, with its own output in result. |
400 | Invalid arguments (INVALID_ARGUMENTS; details says what) or a malformed Idempotency-Key (INVALID_IDEMPOTENCY_KEY). |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA); the plan does not include acting through the API (SCOPE_REVOKED_BY_PLAN); X-Seomatic-Client is n8n or make and the workspace has no paid plan or trial (AUTOMATION_NOT_ENTITLED); the free monthly question limit is reached (FREE_QUOTA_EXCEEDED; body carries keep_going_url and a question_pack payment link); the subscription is paused or its card was declined (BILLING_INACTIVE; body links the one step that restores it, never an upgrade); or the tool refused for credits (INSUFFICIENT_CREDITS, PAYMENT_REQUIRED; body carries the tool result); or the tool hit a plan limit (the code is the refusal code itself: PROMPT_LIMIT, CADENCE_LIMIT, MONITOR_LIMIT, PAGE_LIMIT_EXCEEDED, SEAT_LIMIT_EXCEEDED, WORKSPACE_LIMIT_EXCEEDED, PLANNER_DISABLED, AUTO_EXECUTE_DISABLED, AGENT_SKILLS_NOT_ENTITLED, PAGE_TEMPLATES_NOT_ENTITLED, HOSTED_PAGES_NOT_ENTITLED, AI_ATTRIBUTION_NOT_ENTITLED, ZAPIER_NOT_ENTITLED, BYO_KEYS_NOT_ENTITLED, INCREMENTALITY_NOT_ENTITLED, WEBHOOKS_NOT_ENTITLED; `result` holds the tool refusal). Body carries upgrade_url (and reason, for tool refusals) where an upgrade is the fix. |
403 | The plan allows it but the key creator's role in the workspace does not (FORBIDDEN_ROLE; e.g. a creator now a viewer calling an acting tool). No upgrade fixes it: an admin changes the role. |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
409 | A request with this Idempotency-Key is still running (IDEMPOTENCY_IN_PROGRESS; repeat after Retry-After to collect the result), or it ran and its answer was too large to keep (IDEMPOTENCY_RESULT_NOT_KEPT; it is not run again). |
413 | Request body over 256 KB (BODY_TOO_LARGE). Tool arguments are small JSON objects. |
422 | The tool refused: it needs a confirmation step first (NEEDS_CONFIRMATION), or it declined for another reason it states (TOOL_REFUSED); result holds its explanation. Or this Idempotency-Key was used for a different tool or arguments (IDEMPOTENCY_KEY_REUSED). |
429 | Rate limited: the per-key tool-call limit (Retry-After header set), or the tool refused for a rate cap (e.g. ARTICLE_FAILURE_CAP; body carries the tool result). |
502 | Tool execution failed (TOOL_FAILED) |
503 | Temporarily unavailable, on our side, not a limit: the upstream data provider or the credit check is down (PROVIDER_UNAVAILABLE; nothing was charged), or idempotency is unavailable and the tool was NOT run (IDEMPOTENCY_UNAVAILABLE). Retry shortly. |
504 | The tool is still running past the 60s response ceiling and was not stopped (TOOL_TIMEOUT). With an Idempotency-Key, repeat the request to collect its answer. |
curl -X POST "https://app.seomatic.ai/api/v1/tools/get_referral_link" \
-H "Authorization: Bearer $SEOMATIC_API_KEY"/tools/billing_statusreadThe workspace's plan, status (active, trial, paused, cancelling), next renewal or end date, workspaces in use and whether an extra workspace can be added without a plan change, free questions left on…
| Status | Description |
|---|---|
200 | { tool, result }: the tool answered. result is its output, usually a JSON string (parse it). A tool that refuses does NOT answer 200: it gets the matching 402/422/429/503 below, with its own output in result. |
400 | Invalid arguments (INVALID_ARGUMENTS; details says what) or a malformed Idempotency-Key (INVALID_IDEMPOTENCY_KEY). |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA); the plan does not include acting through the API (SCOPE_REVOKED_BY_PLAN); X-Seomatic-Client is n8n or make and the workspace has no paid plan or trial (AUTOMATION_NOT_ENTITLED); the free monthly question limit is reached (FREE_QUOTA_EXCEEDED; body carries keep_going_url and a question_pack payment link); the subscription is paused or its card was declined (BILLING_INACTIVE; body links the one step that restores it, never an upgrade); or the tool refused for credits (INSUFFICIENT_CREDITS, PAYMENT_REQUIRED; body carries the tool result); or the tool hit a plan limit (the code is the refusal code itself: PROMPT_LIMIT, CADENCE_LIMIT, MONITOR_LIMIT, PAGE_LIMIT_EXCEEDED, SEAT_LIMIT_EXCEEDED, WORKSPACE_LIMIT_EXCEEDED, PLANNER_DISABLED, AUTO_EXECUTE_DISABLED, AGENT_SKILLS_NOT_ENTITLED, PAGE_TEMPLATES_NOT_ENTITLED, HOSTED_PAGES_NOT_ENTITLED, AI_ATTRIBUTION_NOT_ENTITLED, ZAPIER_NOT_ENTITLED, BYO_KEYS_NOT_ENTITLED, INCREMENTALITY_NOT_ENTITLED, WEBHOOKS_NOT_ENTITLED; `result` holds the tool refusal). Body carries upgrade_url (and reason, for tool refusals) where an upgrade is the fix. |
403 | The plan allows it but the key creator's role in the workspace does not (FORBIDDEN_ROLE; e.g. a creator now a viewer calling an acting tool). No upgrade fixes it: an admin changes the role. |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
409 | A request with this Idempotency-Key is still running (IDEMPOTENCY_IN_PROGRESS; repeat after Retry-After to collect the result), or it ran and its answer was too large to keep (IDEMPOTENCY_RESULT_NOT_KEPT; it is not run again). |
413 | Request body over 256 KB (BODY_TOO_LARGE). Tool arguments are small JSON objects. |
422 | The tool refused: it needs a confirmation step first (NEEDS_CONFIRMATION), or it declined for another reason it states (TOOL_REFUSED); result holds its explanation. Or this Idempotency-Key was used for a different tool or arguments (IDEMPOTENCY_KEY_REUSED). |
429 | Rate limited: the per-key tool-call limit (Retry-After header set), or the tool refused for a rate cap (e.g. ARTICLE_FAILURE_CAP; body carries the tool result). |
502 | Tool execution failed (TOOL_FAILED) |
503 | Temporarily unavailable, on our side, not a limit: the upstream data provider or the credit check is down (PROVIDER_UNAVAILABLE; nothing was charged), or idempotency is unavailable and the tool was NOT run (IDEMPOTENCY_UNAVAILABLE). Retry shortly. |
504 | The tool is still running past the 60s response ceiling and was not stopped (TOOL_TIMEOUT). With an Idempotency-Key, repeat the request to collect its answer. |
curl -X POST "https://app.seomatic.ai/api/v1/tools/billing_status" \
-H "Authorization: Bearer $SEOMATIC_API_KEY"/tools/contact_supportreadReach the SEOmatic team: returns the support email and, when message is given, passes the message to the team (they reply by email). Use when the user asks for a person, reports a bug, or has a billi…
| Name | Type | Required | Description |
|---|---|---|---|
message | string | no | The user's problem or question in their words. Omit to just get the address. |
email | string | no | A reply address, only if the user gave one different from their account email. |
| Status | Description |
|---|---|
200 | { tool, result }: the tool answered. result is its output, usually a JSON string (parse it). A tool that refuses does NOT answer 200: it gets the matching 402/422/429/503 below, with its own output in result. |
400 | Invalid arguments (INVALID_ARGUMENTS; details says what) or a malformed Idempotency-Key (INVALID_IDEMPOTENCY_KEY). |
402 | Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA); the plan does not include acting through the API (SCOPE_REVOKED_BY_PLAN); X-Seomatic-Client is n8n or make and the workspace has no paid plan or trial (AUTOMATION_NOT_ENTITLED); the free monthly question limit is reached (FREE_QUOTA_EXCEEDED; body carries keep_going_url and a question_pack payment link); the subscription is paused or its card was declined (BILLING_INACTIVE; body links the one step that restores it, never an upgrade); or the tool refused for credits (INSUFFICIENT_CREDITS, PAYMENT_REQUIRED; body carries the tool result); or the tool hit a plan limit (the code is the refusal code itself: PROMPT_LIMIT, CADENCE_LIMIT, MONITOR_LIMIT, PAGE_LIMIT_EXCEEDED, SEAT_LIMIT_EXCEEDED, WORKSPACE_LIMIT_EXCEEDED, PLANNER_DISABLED, AUTO_EXECUTE_DISABLED, AGENT_SKILLS_NOT_ENTITLED, PAGE_TEMPLATES_NOT_ENTITLED, HOSTED_PAGES_NOT_ENTITLED, AI_ATTRIBUTION_NOT_ENTITLED, ZAPIER_NOT_ENTITLED, BYO_KEYS_NOT_ENTITLED, INCREMENTALITY_NOT_ENTITLED, WEBHOOKS_NOT_ENTITLED; `result` holds the tool refusal). Body carries upgrade_url (and reason, for tool refusals) where an upgrade is the fix. |
403 | The plan allows it but the key creator's role in the workspace does not (FORBIDDEN_ROLE; e.g. a creator now a viewer calling an acting tool). No upgrade fixes it: an admin changes the role. |
404 | Unknown or unauthorized tool (UNKNOWN_TOOL) |
409 | A request with this Idempotency-Key is still running (IDEMPOTENCY_IN_PROGRESS; repeat after Retry-After to collect the result), or it ran and its answer was too large to keep (IDEMPOTENCY_RESULT_NOT_KEPT; it is not run again). |
413 | Request body over 256 KB (BODY_TOO_LARGE). Tool arguments are small JSON objects. |
422 | The tool refused: it needs a confirmation step first (NEEDS_CONFIRMATION), or it declined for another reason it states (TOOL_REFUSED); result holds its explanation. Or this Idempotency-Key was used for a different tool or arguments (IDEMPOTENCY_KEY_REUSED). |
429 | Rate limited: the per-key tool-call limit (Retry-After header set), or the tool refused for a rate cap (e.g. ARTICLE_FAILURE_CAP; body carries the tool result). |
502 | Tool execution failed (TOOL_FAILED) |
503 | Temporarily unavailable, on our side, not a limit: the upstream data provider or the credit check is down (PROVIDER_UNAVAILABLE; nothing was charged), or idempotency is unavailable and the tool was NOT run (IDEMPOTENCY_UNAVAILABLE). Retry shortly. |
504 | The tool is still running past the 60s response ceiling and was not stopped (TOOL_TIMEOUT). With an Idempotency-Key, repeat the request to collect its answer. |
curl -X POST "https://app.seomatic.ai/api/v1/tools/contact_support" \
-H "Authorization: Bearer $SEOMATIC_API_KEY"Ingest endpoints the SEOmatic WordPress plugin reports into.
/wp-eventReport a lifecycle moment a plugin detected on the site it runs on.
For facts only the site itself can see (for example robots.txt blocking AI crawlers, which is read from the site's own filesystem rather than guessed from outside). The event name is validated against a known set; unlisted events are rejected rather than silently recorded.
| 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 $SEOMATIC_API_KEY" \
-H "Content-Type: application/json" \
-d '{"event":"…"}'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 $SEOMATIC_API_KEY"/webhooksRegister a webhook endpoint. The signing secret is returned IN FULL exactly once. Every delivery is a POST with headers X-Seomatic-Event, X-Seomatic-Delivery, X-Seomatic-Timestamp (unix seconds) and X-Seomatic-Signature: `t=<timestamp>,v1=<hex>`, where v1 = HMAC-SHA256(secret, `<timestamp>.<raw body>`). During a secret rotation the header carries one v1 per active secret (`t=..,v1=<new>,v1=<old>`): accept the event if ANY v1 matches. Verify with a constant-time compare and reject timestamps older than a few minutes (replay). Respond 410 Gone to unsubscribe: the endpoint is removed.
| 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 $SEOMATIC_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url":"https://example.com/hooks/seomatic"}'/webhooks/{webhookId}/rotate-secretRotate the signing secret without changing the endpoint id. The new secret is returned IN FULL exactly once. For 24 hours each delivery is signed with both the new and the old secret (two v1 entries), so you can switch your verifier with no dropped events. Rotating again inside that window replaces the older secret immediately.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
webhookId | path | string (uuid) | yes |
| Status | Description |
|---|---|
200 | New secret (shown once) and when the old one stops signing |
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 POST "https://app.seomatic.ai/api/v1/webhooks/$WEBHOOK_ID/rotate-secret" \
-H "Authorization: Bearer $SEOMATIC_API_KEY"/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/$WEBHOOK_ID" \
-H "Authorization: Bearer $SEOMATIC_API_KEY"/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/$WEBHOOK_ID" \
-H "Authorization: Bearer $SEOMATIC_API_KEY"The endpoints behind the Zapier integration (reads on any paid plan; actions on Infrastructure).
/zapier/meZapier connection test: verifies the key and that the workspace has a paid plan or trial.
| Status | Description |
|---|---|
200 | Workspace label + scopes |
401 | Missing or invalid API key |
402 | No paid plan or trial (Zapier needs one) |
429 | Rate limited (per key). Retry-After header set. |
curl -X GET "https://app.seomatic.ai/api/v1/zapier/me" \
-H "Authorization: Bearer $SEOMATIC_API_KEY"/zapier/subscribeRegister a Zapier REST-hook for an event (page.published, task.completed, task.live, 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 | task.awaiting_approval | task.live | 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 | No paid plan or trial (Zapier needs one) |
429 | Rate limited (per key). Retry-After header set. |
curl -X POST "https://app.seomatic.ai/api/v1/zapier/subscribe" \
-H "Authorization: Bearer $SEOMATIC_API_KEY" \
-H "Content-Type: application/json" \
-d '{"targetUrl":"https://example.com/page","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 | Always allowed, whatever the plan (teardown is never paid). `deleted` is true when a subscription was removed. |
401 | Missing or invalid API key |
429 | Rate limited (per key). Retry-After header set. |
curl -X POST "https://app.seomatic.ai/api/v1/zapier/unsubscribe" \
-H "Authorization: Bearer $SEOMATIC_API_KEY" \
-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 | No paid plan or trial (Zapier needs one) |
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 $SEOMATIC_API_KEY"/zapier/triggers/recentPolling trigger and sample data for any event: the workspace's real recent events (what was delivered, else rebuilt from its pages and tasks), newest first. Empty when there is nothing real yet.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
event | query | string | yes | The webhook event, e.g. task.awaiting_approval or task.live. |
| Status | Description |
|---|---|
200 | Array of event envelopes { id, event, workspace_id, created_at, data } |
400 | Unknown event (INVALID_EVENT) |
401 | Missing or invalid API key |
402 | No paid plan or trial (Zapier needs one) |
429 | Rate limited (per key). Retry-After header set. |
curl -X GET "https://app.seomatic.ai/api/v1/zapier/triggers/recent?event=%E2%80%A6" \
-H "Authorization: Bearer $SEOMATIC_API_KEY"/zapier/actions/submit-urlAction: submit a URL through IndexNow (Bing, Naver, Yandex, Seznam) and IndexMeNow when set up. Google accepts direct submissions only for job posting and livestream pages; the response carries a hint when the URL was not sent to Google. Requires Infrastructure (acting over REST).
| Name | In | Type | Required | Description |
|---|---|---|---|---|
Idempotency-Key | header | string | no | Makes the call safe to repeat. Only a submission (200) is kept, for 24h: a repeat returns it (Idempotent-Replayed: true) and never submits twice. A refusal (422 NOT_SUBMITTED) or a failure is not kept, so the same key runs again once IndexNow or IndexMeNow is set up. |
| 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 the workspace has no paid plan or trial |
403 | The key creator's role in the workspace cannot make changes (FORBIDDEN_ROLE). |
422 | Nothing is set up to submit the URL (NOT_SUBMITTED): turn on IndexNow or add an IndexMeNow key. Not kept under an Idempotency-Key. |
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 $SEOMATIC_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url":"https://example.com/page"}'More endpoints of the API, listed here so every endpoint is documented.
/me/revokeRevoke the calling API key itself (for example when an integration or browser extension is disconnected). It can only revoke the key that makes the request; an already invalid key also gets 204, so the call is safe to repeat.
| Status | Description |
|---|---|
204 | The key is revoked (or was already invalid). |
curl -X POST "https://app.seomatic.ai/api/v1/me/revoke" \
-H "Authorization: Bearer $SEOMATIC_API_KEY"/indexnow/registerRegister the IndexNow key the site hosts (Instant Indexing plugin).
Saves the workspace's IndexNow integration from a key the site already hosts. keyLocation must be the site's own {key}.txt URL on the site this key was paired on; the file is fetched and must contain exactly the key before anything is saved.
| Name | Type | Required | Description |
|---|---|---|---|
key | string | yes | IndexNow key, 8-128 of [a-zA-Z0-9-]. |
keyLocation | string | yes | The site's own https://host/{key}.txt URL. |
| Status | Description |
|---|---|
200 | Verified and saved |
400 | Invalid key or key location |
409 | Key file is on another site than the paired one |
422 | Key file did not answer with the key |
curl -X POST "https://app.seomatic.ai/api/v1/indexnow/register" \
-H "Authorization: Bearer $SEOMATIC_API_KEY" \
-H "Content-Type: application/json" \
-d '{"key":"…","keyLocation":"…"}'/indexnow/registerDisable the IndexNow key the plugin registered.
Called by the plugin on disconnect or uninstall. Disables only an integration the plugin registered, never a key set in SEOmatic settings. Optional body: { key }.
| Status | Description |
|---|---|
200 | Result |
curl -X DELETE "https://app.seomatic.ai/api/v1/indexnow/register" \
-H "Authorization: Bearer $SEOMATIC_API_KEY"A REST API over HTTPS with Bearer auth and JSON in and out. It gives your own code the same tools SEOmatic's agents use: Search Console data, site audits, indexing checks, AI visibility, SEO tasks and articles. GET /tools lists every tool your key can call and POST /tools/{name} runs one.
Yes. A free workspace can create an API key. Tool calls and questions share 5 free questions a month with the app and the MCP server, and direct Search Console reads (GET /gsc/*) do not use them. GET /me shows what is left. Paid plans remove the question limit.
Only with a key that has the agents:act scope, which is paid, and acting tools over REST need the Infrastructure plan. Changes are staged as proposals and follow the workspace's autonomy mode: by default each one waits for a person to approve it, and applied edits can be rolled back.
Yes. The OpenAPI 3.1 document is at https://app.seomatic.ai/api/v1/openapi.json, and this reference is generated from it.
Use the API from your own code, scripts, reports and automations. Use the MCP server when an AI assistant such as Claude, ChatGPT or Cursor should call the tools for you. Both run the same tools on the same workspace.