Documentation

API Reference

Workflow POST endpoints are usually async-first. Utility and system endpoints such as /extract , /webhooks/endpoints , and /webhooks/deliveries/{id}/retry are synchronous. Use ?sync=true on supported endpoints to open a short inline processing window. If a result is not ready yet, the API returns 202 with a job payload you can poll.

Most queued workflow endpoints return a standard async envelope with poll_url, events_url, and retry_after_seconds. The main exception is /audit/local/batch, which returns an array of queued job IDs instead of one pollable job envelope.

Use this page when the contract question is already clear

API reference is the right place once you know the runtime path and the workflow job. If you still need to prove category fit, workflow shape, or the first successful request, take one of the shorter routes below first.

Need the first successful request?

Start with quickstart if you still need to validate auth, queued jobs, polling, and the normal request shape.

Need the workflow job first?

Start with use cases if the bigger question is where AgentSEO fits in your app, agent, or review loop.

Still evaluating the API shape?

Use the buyer guide if you are still comparing workflow APIs, SERP APIs, and raw data APIs.

Async Flow

Queue work with any async endpoint, then use the returned poll_url, events_url, and retry_after_seconds fields from the queued payload. You can also poll /jobs/{id} or stream /jobs/{id}/events.

Deterministic Geo

Geo-targeted endpoints accept human-friendly location and optional location_code. If both are provided, location_code wins.

Local Audit Input

domain on /audit/local can be a business name or a domain.

Agent Workflow Block

Core workflow endpoints include agent_workflow with a decision, confidence, recommended actions, evidence, limitations, and next calls for downstream agents.

Request Attribution

Optional x-project-id and x-workflow-id headers are stored on usage logs and async jobs. The official SDK, OpenClaw plugin, and MCP surfaces can set these defaults once for you. Polling /jobs/{id} returns the same context back.

Core Workflows

POST/audit/local

Run a local listing audit (AEO starter) for one business/location and return listing readiness plus an agent_workflow action plan.

Parameters

Name	Type	Description
domain *	string	Business name or domain (e.g. Cool Creek Family Dental or example.com)
location *	string	Full address or city + state/zip
language	string	ISO code (default: en)

Example

curl -X POST https://www.agentseo.dev/api/v1/audit/local?sync=true \
  -H "x-api-key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"domain":"plumber-nyc.com", "location":"Manhattan, NY"}'

POST/audit/local/batch

Queue multiple local audits at once. Utility endpoint for agencies and agent batches. Returns a 202 response with success, message, and a jobs array of queued job IDs.

Parameters

Name	Type	Description
items *	array	List of audit objects (max 10)

Example

curl -X POST https://www.agentseo.dev/api/v1/audit/local/batch \
  -H "x-api-key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"items": [{"domain":"a.com","location":"NY"}, {"domain":"b.com","location":"LA"}]}'

POST/content/gap

Identify missing topics and return an agent_workflow plus a compact content_brief for what to publish or refresh next.

Parameters

Name	Type	Description
url *	string	Your target URL
keyword *	string	Main target keyword
location	string	Target location (default: US)
location_code	integer	Optional search location code for deterministic geo-targeting
language	string	ISO code (default: en)
scrape_depth	enum	h1, h2, or h3 (default: h3)

Example

curl -X POST https://www.agentseo.dev/api/v1/content/gap?sync=true \
  -H "x-api-key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"url":"https://mysite.com/blog/seo", "keyword":"seo tips", "location":"Austin, TX", "location_code":1026201}'

POST/content/refresh-brief

Turn an existing URL and keyword into an implementation-ready refresh brief with gap evidence, sections to add, title/H1 guidance, internal-link tasks, schema recommendations, validation checklist, agent_workflow, and markdown_summary. Requests cost 12 credits.

Parameters

Name	Type	Description
url *	string	Existing page URL to refresh
keyword *	string	Main target keyword
location	string	Target location (default: United States)
location_code	integer	Optional search location code for deterministic geo-targeting
language	string	ISO code (default: en)
scrape_depth	enum	h1, h2, or h3 (default: h3)
current_rank	integer	Known current rank for priority shaping
refresh_goal	string	recover_rankings, improve_conversions, win_featured_snippet, improve_ai_visibility, or expand_topic_depth

Example

curl -X POST https://www.agentseo.dev/api/v1/content/refresh-brief?sync=true \
  -H "x-api-key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"url":"https://mysite.com/blog/seo", "keyword":"seo tips", "location":"United States", "current_rank":12, "refresh_goal":"expand_topic_depth"}'

POST/content/serp-outline

Turn a live SERP into a writer- and agent-ready page outline with title options, H2 sections, questions to answer, schema recommendations, validation checklist, agent_workflow, and markdown_summary. Requests cost 4 credits.

Parameters

Name	Type	Description
keyword *	string	Main target keyword
target	string	Optional target brand, domain, or product to route the outline toward
location	string	Target location (default: United States)
location_code	integer	Optional search location code for deterministic geo-targeting
language	string	ISO code (default: en)
device	enum	desktop or mobile (default: desktop)
outline_depth	enum	brief, standard, or detailed (default: standard)
include_title_options	boolean	Return title options with the outline (default: true)

Example

curl -X POST https://www.agentseo.dev/api/v1/content/serp-outline?sync=true \
  -H "x-api-key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"keyword":"seo api", "target":"AgentSEO", "location":"United States", "outline_depth":"standard"}'

POST/content/brief

Turn a live SERP into a production-ready content brief with audience, meta, SERP expectations, competitor patterns, differentiators, proof requirements, conversion plan, QA checklist, optional outline, agent_workflow, and markdown_summary. Requests cost 6 credits.

Parameters

Name	Type	Description
keyword *	string	Main target keyword
target	string	Optional target brand, domain, or product
audience	string	Optional audience description for writer guidance
location	string	Target location (default: United States)
language	string	ISO code (default: en)
device	enum	desktop or mobile (default: desktop)
brand_voice	enum	neutral, expert, friendly, bold, or technical (default: expert)
page_type	enum	auto, blog_post, landing_page, comparison_page, guide, or tool_page
brief_depth	enum	standard or detailed (default: standard)
include_serp_outline	boolean	Include the structured SERP outline in the response (default: true)

Example

curl -X POST https://www.agentseo.dev/api/v1/content/brief?sync=true \
  -H "x-api-key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"keyword":"seo api", "target":"AgentSEO", "audience":"technical marketers", "location":"United States", "brief_depth":"standard"}'

POST/content/draft-qa

Validate a draft URL or markdown against live SERP expectations before publishing. Returns publish_readiness_score, readiness, missing SERP expectations, weak sections, proof gaps, title/meta issues, schema recommendations, editor tasks, agent_workflow, and markdown_summary. Requests cost 8 credits.

Parameters

Name	Type	Description
keyword *	string	Main target keyword
draft_url	string	Draft or staged page URL to scrape
draft_markdown	string	Draft markdown when a URL is not available. Either draft_url or draft_markdown is required.
target	string	Optional target brand, domain, or product
location	string	Target location (default: United States)
language	string	ISO code (default: en)
device	enum	desktop or mobile (default: desktop)
qa_depth	enum	standard or strict (default: standard)

Example

curl -X POST https://www.agentseo.dev/api/v1/content/draft-qa?sync=true \
  -H "x-api-key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"keyword":"seo api", "target":"AgentSEO", "location":"United States", "draft_markdown":"# SEO API Guide\n\nThis draft explains what an SEO API is and how marketers use SERP data before publishing."}'

POST/content/schema-plan

Plan JSON-LD schema for a URL or markdown page without a paid provider call. Returns recommended schema types, JSON-LD draft, required fields checklist, missing page evidence, FAQ candidates, implementation notes, validation checklist, agent_workflow, and markdown_summary. Requests cost 3 credits.

Parameters

Name	Type	Description
url	string	Page URL to scrape. Either url or page_markdown is required.
page_markdown	string	Page markdown when a URL is not available.
page_type	enum	auto, article, blog_post, landing_page, product, software, local_business, faq, or how_to
keyword	string	Optional target keyword for context
target	string	Optional target brand, domain, or product
include_jsonld	boolean	Include JSON-LD draft blocks (default: true)

Example

curl -X POST https://www.agentseo.dev/api/v1/content/schema-plan?sync=true \
  -H "x-api-key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"keyword":"seo api", "target":"AgentSEO", "page_type":"software", "include_jsonld":true, "page_markdown":"# SEO API Platform\n\nAgentSEO is a software platform for marketers that need structured SEO workflows."}'

POST/content/internal-links

Find internal link opportunities from a source URL or markdown page to supplied target pages. Returns ranked placements, suggested anchor text, crawlability guardrails, review notes, agent_workflow, and markdown_summary. Requests cost 2 credits and do not call a paid SERP provider.

Parameters

Name	Type	Description
source_url	string	Source page URL to scrape. Either source_url or source_markdown is required.
source_markdown	string	Source page markdown when a URL is not available.
target_pages *	array	Required candidate internal target pages with url, title, optional description, and optional keywords. Use 1-50 pages from your sitemap, CMS, crawler, Search Console, or /site/sitemap-audit.
keyword	string	Optional source page target keyword for anchor review.
target	string	Optional target brand, domain, or product
max_suggestions	integer	Maximum link suggestions to return (default: 8, max: 20)

Example

curl -X POST https://www.agentseo.dev/api/v1/content/internal-links?sync=true \
  -H "x-api-key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"keyword":"seo api", "target":"AgentSEO", "source_markdown":"# SEO API Guide\n\nThis guide explains SEO APIs, content briefs, draft QA, schema planning, and internal links.", "target_pages":[{"url":"https://www.agentseo.dev/docs/api-reference","title":"AgentSEO API Reference","description":"Reference documentation for AgentSEO endpoints.","keywords":["seo api reference","agentseo api"]}]}'

POST/content/title-meta

Generate SEO title and meta description options for a URL or markdown page. Returns title options, meta description options, current signal checks, snippet risks, implementation checklist, agent_workflow, and markdown_summary. Requests cost 2 credits and do not call a paid SERP provider.

Parameters

Name	Type	Description
keyword *	string	Primary target keyword or query
url	string	Page URL to scrape. Either url or page_markdown is required.
page_markdown	string	Page markdown when a URL is not available.
target	string	Optional target brand, domain, or product
page_type	enum	auto, blog_post, landing_page, product, software, local_business, comparison_page, or guide
current_title	string	Optional current title element to audit
current_meta_description	string	Optional current meta description to audit

Example

curl -X POST https://www.agentseo.dev/api/v1/content/title-meta?sync=true \
  -H "x-api-key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"keyword":"seo api", "target":"AgentSEO", "page_type":"software", "page_markdown":"# SEO API Platform\n\nAgentSEO helps marketers create content briefs, QA drafts, prepare schema, improve internal links, and optimize metadata before publishing useful SEO pages."}'

POST/content/keyword-map

Map supplied keywords to supplied pages before drafting or refreshing content. Returns primary URL recommendations, weak matches, missing-page opportunities, cannibalization risks, implementation checklist, agent_workflow, and markdown_summary. Requests cost 2 credits and do not call a paid SERP provider.

Parameters

Name	Type	Description
keywords *	array	Keyword list to map. Maximum 250 keywords.
pages *	array	Candidate pages with url, title, optional description, headings, current_keywords, and page_type.
target	string	Optional target brand, domain, or product
max_mappings	integer	Maximum keyword mappings to return (default: 250)

Example

curl -X POST https://www.agentseo.dev/api/v1/content/keyword-map?sync=true \
  -H "x-api-key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"target":"AgentSEO","keywords":["seo api","seo api pricing","best seo api"],"pages":[{"url":"https://www.agentseo.dev/docs/api-reference","title":"AgentSEO API Reference","description":"Reference documentation for AgentSEO endpoints.","current_keywords":["seo api","agentseo api"],"page_type":"docs"},{"url":"https://www.agentseo.dev/pricing","title":"AgentSEO Pricing","description":"Pricing for AgentSEO plans.","current_keywords":["seo api pricing"],"page_type":"landing_page"}]}'

POST/content/technical-qa

Run pre-publish technical SEO QA for a URL, HTML page, or markdown draft. Returns indexability, metadata, canonical, heading, structured-data, internal-link, image-alt, readiness-score, publish checklist, agent_workflow, and markdown_summary checks. Requests cost 2 credits and do not call a paid SERP provider.

Parameters

Name	Type	Description
url	string	Live page URL to fetch and inspect. Provide url, html, or markdown.
html	string	Raw HTML for unpublished or staging pages.
markdown	string	Markdown draft when HTML is not available.
keyword	string	Optional target keyword for title alignment checks.
expected_canonical	string	Expected canonical URL. Mismatches are treated as high severity.
page_type	enum	auto, article, blog_post, landing_page, product, software, local_business, comparison_page, guide, or docs

Example

curl -X POST https://www.agentseo.dev/api/v1/content/technical-qa?sync=true \
  -H "x-api-key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"keyword":"seo api", "target":"AgentSEO", "expected_canonical":"https://www.agentseo.dev/docs/api-reference", "page_type":"software", "html":"<html><head><title>SEO API Platform for Technical Marketers | AgentSEO</title><meta name=\"description\" content=\"Review an SEO API platform before publishing with metadata, canonical, schema, headings, and internal-link checks.\"><link rel=\"canonical\" href=\"https://www.agentseo.dev/docs/api-reference\"><meta name=\"robots\" content=\"index,follow\"></head><body><h1>SEO API Platform</h1><h2>Publishing workflow</h2><p>AgentSEO helps marketers validate pages before publishing useful SEO pages.</p><a href=\"https://www.agentseo.dev/docs\">Docs</a></body></html>"}'

POST/content/action-plan

Turn supplied SEO opportunities, refresh candidates, technical fixes, and link tasks into a capacity-aware content calendar. Returns scheduled actions, weekly buckets, risk register, agent_workflow, and markdown_summary. Requests cost 2 credits and do not call a paid SERP provider.

Parameters

Name	Type	Description
items *	array	Opportunity items to schedule. Each item needs a title; keyword, url, priority, impact_score, effort, status, and dependencies improve planning.
target	string	Optional target brand, domain, or product.
goal	enum	traffic_growth, lead_generation, refresh_decay, launch_support, or authority_building.
horizon_days	integer	Planning horizon from 7 to 90 days. Default: 30.
weekly_capacity	integer	Maximum effort points to schedule per week. Default: 5.
team	array	Optional assignee names for round-robin ownership.

Example

curl -X POST https://www.agentseo.dev/api/v1/content/action-plan?sync=true \
  -H "x-api-key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"target":"AgentSEO","goal":"traffic_growth","horizon_days":30,"weekly_capacity":3,"team":["Editor","Dan"],"items":[{"title":"Refresh SEO API docs","keyword":"seo api","url":"https://www.agentseo.dev/docs/api-reference","opportunity_type":"refresh","buyer_stage":"consideration","priority":"critical","impact_score":92,"effort":"medium","status":"ready","dependencies":[]},{"title":"Publish best SEO API comparison","keyword":"best seo api","opportunity_type":"new_content","buyer_stage":"decision","priority":"high","impact_score":80,"effort":"medium","status":"idea","dependencies":["SERP outline"]}]}'

POST/site/sitemap-audit

Audit sitemap coverage, sitemap-only orphan candidates, important URLs, canonical/indexability noise, and internal-link gaps. Returns findings, severity counts, implementation checklist, agent_workflow, and markdown_summary. Requests cost 2 credits and do not call a paid search API.

Parameters

Name	Type	Description
sitemap_url	string	Sitemap URL to fetch. Provide sitemap_url or sitemap_xml.
sitemap_xml	string	Raw sitemap XML. Useful for staging sites, pasted exports, or tests.
important_urls	array	High-priority URLs that should usually be in the sitemap and internally linked.
crawl_urls	array	Optional crawl/CMS/Search Console URL export with url, status_code, indexable, canonical_url, inbound_internal_links, clicks, and impressions.
internal_links	array	Optional internal-link export with source_url, target_url, and anchor.
max_sitemap_children	integer	When sitemap_url is a sitemap index, fetch up to this many child sitemaps. Default: 3, max: 10.

Example

curl -X POST https://www.agentseo.dev/api/v1/site/sitemap-audit?sync=true \
  -H "x-api-key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"target":"AgentSEO","sitemap_xml":"<?xml version=\"1.0\" encoding=\"UTF-8\"?><urlset xmlns=\"http://www.sitemaps.org/schemas/sitemap/0.9\"><url><loc>https://www.agentseo.dev/docs/api-reference</loc><lastmod>2026-07-16</lastmod></url><url><loc>https://www.agentseo.dev/old-page</loc></url></urlset>","max_sitemap_children":0,"important_urls":["https://www.agentseo.dev/docs/api-reference","https://www.agentseo.dev/pricing"],"crawl_urls":[{"url":"https://www.agentseo.dev/docs/api-reference","status_code":200,"indexable":true,"inbound_internal_links":4},{"url":"https://www.agentseo.dev/old-page","status_code":404,"indexable":false,"inbound_internal_links":0},{"url":"https://www.agentseo.dev/pricing","status_code":200,"indexable":true,"inbound_internal_links":2}],"internal_links":[{"source_url":"https://www.agentseo.dev/docs","target_url":"https://www.agentseo.dev/docs/api-reference","anchor":"API reference"}]}'

POST/serp/volatility

Compare supplied SERP snapshots to detect rank movement, top-domain churn, SERP feature changes, winners, losers, and target visibility movement. Returns volatility score, interpretation, agent_workflow, and markdown_summary. Requests cost 2 credits and do not call a paid search API.

Parameters

Name	Type	Description
keyword *	string	Keyword or query being monitored.
snapshots *	array	At least two SERP snapshots. Each snapshot needs checked_at and ranked results with position and url.
target_domains	array	Domains to track for visibility movement.
location	string	Search location label. Default: United States.
device	enum	desktop or mobile. Default: desktop.
sensitivity	enum	low, medium, or high. Higher sensitivity flags smaller changes.

Example

curl -X POST https://www.agentseo.dev/api/v1/serp/volatility?sync=true \
  -H "x-api-key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"keyword":"seo api","target":"AgentSEO","location":"United States","device":"desktop","sensitivity":"medium","target_domains":["agentseo.dev"],"snapshots":[{"checked_at":"2026-07-10","serp_features":["featured_snippet"],"results":[{"position":1,"url":"https://www.agentseo.dev/docs/api-reference","domain":"agentseo.dev"},{"position":2,"url":"https://example-a.com/seo-api","domain":"example-a.com"},{"position":3,"url":"https://example-b.com/seo-api","domain":"example-b.com"}]},{"checked_at":"2026-07-16","serp_features":["ai_overview","people_also_ask"],"results":[{"position":1,"url":"https://example-c.com/seo-api","domain":"example-c.com"},{"position":2,"url":"https://example-d.com/seo-api","domain":"example-d.com"},{"position":7,"url":"https://www.agentseo.dev/docs/api-reference","domain":"agentseo.dev"}]}]}'

POST/page/cro-qa

Audit an SEO landing page for conversion readiness. Returns value-proposition, CTA, proof, objection-handling, friction, CTA alternatives, agent_workflow, and markdown_summary. Requests cost 2 credits and do not call a paid search API.

Parameters

Name	Type	Description
url	string	Live page URL to fetch and inspect. Provide url, html, or markdown.
html	string	Raw HTML for an unpublished or staging page.
markdown	string	Markdown page draft when HTML is not available.
conversion_goal	enum	signup, trial, demo, purchase, contact_sales, subscribe, download, or learn_more.
page_type	enum	auto, homepage, landing_page, pricing, feature, blog_post, product, comparison_page, or docs.
keyword	string	Target keyword used to check hero/intent alignment.

Example

curl -X POST https://www.agentseo.dev/api/v1/page/cro-qa?sync=true \
  -H "x-api-key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"target":"AgentSEO","keyword":"seo api","page_type":"landing_page","conversion_goal":"trial","traffic_source":"organic","audience":"technical marketers","markdown":"# SEO API for marketers\n\nStart free trial and run your first SEO workflow. AgentSEO helps technical marketers plan, QA, and ship SEO work with clear API outputs.\n\n## Why teams use it\n\nTrusted by marketers who need customer proof, pricing clarity, security details, implementation guidance, and support before they commit.\n\n[Start Free Trial](https://www.agentseo.dev/pricing)\n\n## FAQ\n\nPricing is transparent, setup is simple, and support is available when you need help."}'

POST/content/cannibalization

Detect pages that may be competing for the same keyword intent and recommend safe fixes. Returns page signals, conflicts, clusters, preferred URLs, remediation steps, agent_workflow, and markdown_summary. Requests cost 2 credits and do not call a paid SERP provider.

Parameters

Name	Type	Description
pages *	array	At least two pages with url and title. Add primary_keyword, target_keywords, ranking_queries, page_type, canonical_url, indexable, clicks, impressions, avg_position, and backlinks for better recommendations.
target	string	Optional target brand, domain, or product.
focus_keywords	array	Optional keywords to emphasize when matching page overlap.
sensitivity	enum	conservative, balanced, or aggressive. Default: balanced.

Example

curl -X POST https://www.agentseo.dev/api/v1/content/cannibalization?sync=true \
  -H "x-api-key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"target":"AgentSEO","sensitivity":"balanced","focus_keywords":["seo api","best seo api"],"pages":[{"url":"https://www.agentseo.dev/docs/api-reference","title":"SEO API Reference","primary_keyword":"seo api","target_keywords":["seo api"],"ranking_queries":["seo api"],"page_type":"docs","clicks":80,"impressions":1200,"avg_position":6,"backlinks":12},{"url":"https://www.agentseo.dev/blog/seo-api-guide","title":"SEO API Guide for Marketers","primary_keyword":"seo api","target_keywords":["seo api","best seo api"],"ranking_queries":["seo api"],"page_type":"guide","clicks":10,"impressions":700,"avg_position":18,"backlinks":1}]}'

POST/ai-visibility/prompt-set

Build a stable AI visibility prompt set mapped to platforms, competitors, owned assets, citations, and weekly action routing. Returns prompt buckets, measurement schema, coverage, agent_workflow, and markdown_summary. Requests cost 2 credits and do not run live LLM queries or call a paid search API.

Parameters

Name	Type	Description
target *	string	Brand, product, or domain being monitored.
category *	string	Market/category for the prompt set, for example SEO API.
topics *	array	Topic themes that should appear in category, implementation, citation, and asset-gap prompts.
platforms	array	chatgpt, perplexity, google_ai, gemini, copilot, or claude.
owned_assets	array	Owned URLs with title, page_type, and topics. Used to map prompts back to pages the team can improve.
competitors	array	Competitors to include in comparison prompts.
prompt_count	integer	Number of prompts to return, 6-50. Default: 20.

Example

curl -X POST https://www.agentseo.dev/api/v1/ai-visibility/prompt-set?sync=true \
  -H "x-api-key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"target":"AgentSEO","category":"SEO API","audience":"technical marketers","platforms":["chatgpt","perplexity","google_ai"],"competitors":["Semrush API","Ahrefs API"],"topics":["AI visibility monitoring","content QA","SEO workflow automation"],"product_terms":["content brief API","technical QA API"],"personas":["growth marketer","SEO agency owner"],"owned_assets":[{"url":"https://www.agentseo.dev/docs/api-reference","title":"AgentSEO API Reference","page_type":"docs","topics":["content QA","technical QA API","content brief API"]},{"url":"https://www.agentseo.dev/blog/how-to-measure-ai-visibility","title":"How to measure AI visibility","page_type":"blog_post","topics":["AI visibility monitoring"]}],"prompt_count":12,"cadence":"weekly"}'

POST/content/competitor-gap-matrix

Compare supplied own and competitor pages to find missing topics, weak coverage, format gaps, and buyer-stage gaps. Returns prioritized opportunities, a page-type-by-stage matrix, suggested titles, next endpoints, agent_workflow, and markdown_summary. Requests cost 3 credits and do not call a paid SERP provider.

Parameters

Name	Type	Description
competitors *	array	Competitor objects with domain and pages. Each page needs url and title; keywords, ranking_queries, page_type, buyer_stage, traffic, volume, rank, and backlinks improve scoring.
own_pages	array	Your supplied pages for coverage comparison.
focus_topics	array	Topics to boost when scoring opportunities.
max_opportunities	integer	Maximum opportunities to return. Default: 30, max: 100.

Example

curl -X POST https://www.agentseo.dev/api/v1/content/competitor-gap-matrix?sync=true \
  -H "x-api-key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"target":"AgentSEO","focus_topics":["seo api templates"],"own_pages":[{"url":"https://www.agentseo.dev/docs/api-reference","title":"AgentSEO API Reference","keywords":["seo api"],"page_type":"docs","buyer_stage":"implementation"}],"competitors":[{"domain":"competitor.example","pages":[{"url":"https://competitor.example/templates/seo-api-template","title":"SEO API Template Library","keywords":["seo api templates","seo workflow template"],"ranking_queries":["seo api templates"],"page_type":"template","buyer_stage":"implementation","estimated_traffic":500,"search_volume":900,"avg_position":4,"backlinks":8}]}],"max_opportunities":10}'

POST/content/programmatic-template

Plan safe programmatic SEO templates before building pages at scale. Returns readiness score, scale risk, launch decision, template sections, uniqueness rules, indexation gates, internal-link architecture, schema recommendations, launch plan, agent_workflow, and markdown_summary. Requests cost 2 credits and do not call a paid search API.

Parameters

Name	Type	Description
keyword_pattern *	string	Repeating keyword pattern, for example AgentSEO [integration] integration.
url_pattern *	string	Repeating URL pattern, for example /integrations/[integration]/.
data_sources *	array	Data sources with name, type, freshness, and fields. First-party/product data produces safer scale recommendations than generic public data.
variables *	array	Template variables such as integration, city, category, product, persona, or term.
playbook	enum	templates, curation, conversions, comparisons, examples, locations, personas, integrations, glossary, translations, directory, profiles, or custom.
unique_fields	array	Fields that create page-specific value and reduce thin-content risk.
sample_records	array	Example records from the data model for scoring template completeness.
publishing_cadence	enum	pilot, weekly_batch, monthly_batch, or bulk_import.

Example

curl -X POST https://www.agentseo.dev/api/v1/content/programmatic-template?sync=true \
  -H "x-api-key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"target":"AgentSEO","playbook":"integrations","page_goal":"trial_signup","keyword_pattern":"AgentSEO [integration] integration","url_pattern":"/integrations/[integration]/","audience":"technical marketers","page_count_estimate":80,"data_sources":[{"name":"Product integration catalog","type":"first_party","freshness":"weekly","fields":["integration","setup_steps","use_cases","supported_triggers","pricing_note","limitations","sync_direction","auth_type"]}],"variables":["integration"],"unique_fields":["setup_steps","use_cases","supported_triggers","pricing_note","limitations","sync_direction","auth_type"],"sample_records":[{"integration":"Slack","setup_steps":"Connect workspace and choose alerts","use_cases":"Send SEO QA reports to channels","supported_triggers":"job.completed","pricing_note":"Available on Pro","sync_direction":"outbound alerts","auth_type":"OAuth"}],"competitors":["zapier.com","make.com"],"conversion_cta":"Start free trial","publishing_cadence":"pilot","include_schema":true,"include_internal_linking":true}'

POST/ai-overview/extract

Check whether a query is triggering an AI Overview and return both ai_overview_detected and overview_status, plus a sampled candidate audit, optional target-domain coverage, and an agent_workflow brief.

Parameters

Name	Type	Description
keyword *	string	Search query
location	string	Geographic location
location_code	integer	Optional search location code for deterministic geo-targeting
language	string	ISO code (default: en)
target_domain	string	Optional domain to check against the sampled candidate set (e.g. linkdoctor.io)

Example

curl -X POST https://www.agentseo.dev/api/v1/ai-overview/extract?sync=true \
  -H "x-api-key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"keyword":"how to fix a leak", "location":"Austin, TX", "location_code":1026201, "target_domain":"example.com"}'

POST/rank/track

Queue a rank tracking job for a specific keyword/URL and return an agent_workflow once the check completes.

Parameters

Name	Type	Description
keyword *	string	Target keyword
url *	string	Target URL
location	string	Location string
location_code	integer	Optional search location code for deterministic geo-targeting

Example

curl -X POST https://www.agentseo.dev/api/v1/rank/track?sync=true \
  -H "x-api-key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"keyword":"seo api", "url":"https://www.agentseo.dev", "location":"Austin, TX", "location_code":1026201}'

GET/rank/track

Get rank history for a keyword/URL pair, including agent_workflow summary for the current state.

Parameters

Name	Type	Description
keyword *	string	Target keyword
url *	string	Target URL

Example

curl "https://www.agentseo.dev/api/v1/rank/track?keyword=seo%20api&url=https%3A%2F%2Fwww.agentseo.dev" \
  -H "x-api-key: sk_live_..."

POST/local-visibility/track

Track local pack visibility across multiple keywords and locations and return an agent_workflow summary.

Parameters

Name	Type	Description
domain *	string	Target domain
keywords *	array	List of keywords (max 5)
locations *	array	List of locations (max 3)
location_codes	array	Optional search location codes aligned by index with locations
language	string	ISO code (default: en)

Example

curl -X POST https://www.agentseo.dev/api/v1/local-visibility/track?sync=true \
  -H "x-api-key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"domain":"example.com", "keywords":["pizza"], "locations":["Austin, TX"], "location_codes":[1026201]}'

POST/opportunities/find

Find ranked-keyword opportunities for a domain or URL and return agent-ready priorities, evidence, recommended actions, next API calls, and a markdown summary. Base requests cost 3 credits; SERP competitor enrichment adds 2 credits; domain competitor discovery adds 2 credits.

Parameters

Name	Type	Description
target *	string	Domain, subdomain, or URL to analyze (e.g. example.com or https://example.com/blog)
location	string	Target location (default: United States)
location_code	integer	Optional search location code for deterministic geo-targeting
language	string	ISO code (default: en)
keyword_limit	integer	How many ranked keywords to inspect (10-250, default: 100)
limit	integer	How many opportunities to return (1-25, default: 10)
seed_keywords	array	Optional keywords for SERP competitor enrichment; if omitted, AgentSEO can auto-select ranked keywords
include_serp_competitors	boolean	Add SERP competitor domains for the selected keyword set (+2 credits)
include_competitor_discovery	boolean	Add domain-level competitor gaps and overlap metrics (+2 credits)

Example

curl -X POST https://www.agentseo.dev/api/v1/opportunities/find?sync=true \
  -H "x-api-key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"target":"example.com", "location":"United States", "keyword_limit":10, "limit":3, "include_serp_competitors":true, "include_competitor_discovery":true}'

POST/opportunities/brief

Turn one selected keyword/page opportunity into an implementation-ready brief with SERP intent, sections to add, questions to answer, schema recommendations, validation checklist, agent_workflow, and markdown_summary. Base requests cost 10 credits; competitor outline scraping adds 2 credits.

Parameters

Name	Type	Description
keyword *	string	Keyword to analyze and brief
target	string	Target domain, brand, or site being optimized
page_url	string	Existing page URL to inspect for current headings
location	string	Target location (default: United States)
location_code	integer	Optional search location code for deterministic geo-targeting
language	string	ISO code (default: en)
opportunity_type	string	Optional hint such as quick_win, content_refresh, ai_overview_opportunity, featured_snippet_opportunity, commercial_intent_opportunity, lost_keyword_recovery, or competitor_gap
current_rank	integer	Known current rank for priority shaping
include_competitor_outlines	boolean	Scrape headings from top SERP competitors for outline context (+2 credits, default: true)

Example

curl -X POST https://www.agentseo.dev/api/v1/opportunities/brief?sync=true \
  -H "x-api-key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"keyword":"seo api", "target":"example.com", "page_url":"https://example.com/seo-api", "location":"United States", "opportunity_type":"commercial_intent_opportunity", "current_rank":8, "include_competitor_outlines":false}'

Supporting Primitives

POST/search

Perform a Google search with optional domain filtering. Returns raw SERP evidence plus agent_support so an agent can choose the next workflow.

Parameters

Name	Type	Description
query *	string	Search query
location	string	Target location (default: United States)
location_code	integer	Optional search location code for deterministic geo-targeting
language	string	ISO code (default: en)
limit	integer	Max results (1-50, default: 10)
include_domains	array	Only return results from these domains
exclude_domains	array	Exclude results from these domains

Example

curl -X POST https://www.agentseo.dev/api/v1/search?sync=true \
  -H "x-api-key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"query":"best crm software", "location":"Austin, TX", "location_code":1026201, "limit":5}'

POST/extract

Extract clean content (markdown/text/html) from any URL. Returns page metadata, structural headings, and agent_support for follow-up workflow selection.

Parameters

Name	Type	Description
url *	string	Target URL
format	enum	markdown, text, html (default: markdown)
include_images	boolean	Include image extraction (default: false)

Example

curl -X POST https://www.agentseo.dev/api/v1/extract \
  -H "x-api-key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"url":"https://tcrn.ch/example"}'

POST/analyze/serp

Analyze SERP features (Local Pack, AI Overview, Shopping) for a keyword. Returns serp_opportunity so agents can infer intent, competition, and the right content format.

Parameters

Name	Type	Description
keyword *	string	Target keyword
location	string	Target location (default: US)
location_code	integer	Optional search location code for deterministic geo-targeting
device	enum	desktop or mobile (default: desktop)
language	string	ISO code (default: en)

Example

curl -X POST https://www.agentseo.dev/api/v1/analyze/serp?sync=true \
  -H "x-api-key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"keyword":"plumbers near me", "location":"Austin, TX", "location_code":1026201, "device":"mobile"}'

Experimental Workflows

POST/llm-mentions/track

Track prompt-set visibility for a brand across sampled discovery surfaces. Returns mention_audit plus agent_workflow so agents can identify weak queries and decide whether to act or keep monitoring.

Parameters

Name	Type	Description
brand *	string	Brand name
queries *	array	List of queries to test
platform	enum	reddit, twitter, all (default: all)
limit_per_query	integer	Max results per query (1-20, default: 8)

Example

curl -X POST https://www.agentseo.dev/api/v1/llm-mentions/track \
  -H "x-api-key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"brand":"AgentSEO", "queries":["best seo agents"]}'

POST/content-decay/detect

Identify content that is losing ranking momentum over time. Returns decay_audit plus agent_workflow so agents can judge urgency, likely cause, and the right next investigation.

Parameters

Name	Type	Description
url *	string	Page URL to check
keyword *	string	Main keyword
lookback_days	integer	Days to analyze (3-180, default: 30)
threshold	number	Decay threshold % (default: 3)

Example

curl -X POST https://www.agentseo.dev/api/v1/content-decay/detect?sync=true \
  -H "x-api-key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/blog/old-post", "keyword":"legacy keyword"}'

POST/keyword-cluster/build

Group keywords into intent-led clusters and return cluster_plan plus agent_workflow so agents can map cluster targets to the right page types before publishing.

Parameters

Name	Type	Description
keywords *	array	List of keywords (max 200)

Example

curl -X POST https://www.agentseo.dev/api/v1/keyword-cluster/build?sync=true \
  -H "x-api-key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"keywords":["best shoes", "running shoes", "cheap sneakers"]}'

POST/keyword-ideas/suggest

Expand one seed keyword into prioritized long-tail keyword ideas with search volume, CPC, competition, buyer stage, recommended page type, agent_workflow, and markdown_summary. Requests cost 4 credits and use one paid keyword suggestions request with SERP enrichment disabled.

Parameters

Name	Type	Description
keyword *	string	Seed keyword or topic
location	string	Search market (default: United States)
location_code	integer	Optional provider location code. Wins over location when provided.
language	string	Language code or name (default: en)
limit	integer	Number of ideas to return (5-100, default: 25)
min_search_volume	integer	Minimum monthly search volume filter (default: 0)

Example

curl -X POST https://www.agentseo.dev/api/v1/keyword-ideas/suggest?sync=true \
  -H "x-api-key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"keyword":"seo api", "location":"United States", "language":"en", "limit":25, "min_search_volume":10}'

POST/keyword-metrics/overview

Score a supplied keyword list with search volume, CPC, competition, difficulty, buyer stage, recommended page type, opportunity score, agent_workflow, and markdown_summary. Requests cost 5 credits per 25 keywords, minimum 5, with SERP and clickstream enrichment disabled.

Parameters

Name	Type	Description
keywords *	array	Keyword list to score. Maximum 100 keywords.
location	string	Search market (default: United States)
location_code	integer	Optional provider location code. Wins over location when provided.
language	string	Language code or name (default: en)
min_search_volume	integer	Minimum monthly search volume filter (default: 0)
sort_by	enum	priority, search_volume, cpc, or difficulty (default: priority)

Example

curl -X POST https://www.agentseo.dev/api/v1/keyword-metrics/overview?sync=true \
  -H "x-api-key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"keywords":["seo api","best seo api","seo api pricing"], "location":"United States", "language":"en", "min_search_volume":10, "sort_by":"priority"}'

POST/domain/ranked-keywords

Find ranked keywords for a domain, subdomain, or URL and prioritize refresh opportunities with rank, page URL, search metrics, SERP features, movement, opportunity type, agent_workflow, and markdown_summary. Requests cost 5 credits per 100 requested rows, minimum 5, with clickstream enrichment disabled.

Parameters

Name	Type	Description
target *	string	Domain, subdomain, or page URL to inspect.
location	string	Search market (default: United States)
location_code	integer	Optional provider location code. Wins over location when provided.
language	string	Language code or name (default: en)
limit	integer	Rows to request (10-250, default: 50)
min_search_volume	integer	Minimum monthly search volume filter (default: 0)
max_rank	integer	Maximum ranking position to include (1-100, default: 100)
sort_by	enum	opportunity, estimated_traffic, rank, search_volume, or cpc (default: opportunity)
include_lost	boolean	Include lost rankings when available (default: false)

Example

curl -X POST https://www.agentseo.dev/api/v1/domain/ranked-keywords?sync=true \
  -H "x-api-key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"target":"agentseo.dev", "location":"United States", "language":"en", "limit":25, "min_search_volume":10, "max_rank":50, "sort_by":"opportunity"}'

POST/domain/relevant-pages

Find organic traffic-carrying pages for a domain and route them into protect, refresh, expand, recover, or review actions with page metrics, opportunity score, agent_workflow, and markdown_summary. Requests cost 5 credits per 100 requested pages, minimum 5, with clickstream enrichment disabled.

Parameters

Name	Type	Description
target *	string	Domain to inspect, without protocol or www when possible.
location	string	Search market (default: United States)
location_code	integer	Optional provider location code. Wins over location when provided.
language	string	Language code or name (default: en)
limit	integer	Pages to request (10-250, default: 50)
min_traffic	integer	Minimum estimated organic traffic filter (default: 0)
historical_serp_mode	enum	live, lost, or all (default: live)
sort_by	enum	estimated_traffic, keyword_count, top3, or opportunity (default: estimated_traffic)

Example

curl -X POST https://www.agentseo.dev/api/v1/domain/relevant-pages?sync=true \
  -H "x-api-key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"target":"agentseo.dev", "location":"United States", "language":"en", "limit":25, "min_traffic":0, "historical_serp_mode":"live", "sort_by":"estimated_traffic"}'

POST/domain/competitors

Discover search competitors for a domain and prioritize shared keyword overlap, traffic gaps, threat level, next actions, agent_workflow, and markdown_summary. Requests cost 5 credits per 100 requested competitors, minimum 5, with clickstream enrichment disabled.

Parameters

Name	Type	Description
target *	string	Domain or URL to inspect. URLs are normalized to the domain.
location	string	Search market (default: United States)
location_code	integer	Optional provider location code. Wins over location when provided.
language	string	Language code or name (default: en)
limit	integer	Competitors to request (5-250, default: 25)
min_intersections	integer	Minimum shared keyword count filter (default: 0)
max_rank_group	integer	Maximum rank bucket considered for overlap (1-100, default: 20)
sort_by	enum	threat, overlap, competitor_traffic, or traffic_gap (default: threat)

Example

curl -X POST https://www.agentseo.dev/api/v1/domain/competitors?sync=true \
  -H "x-api-key: sk_live_..." \
  -H "Content-Type: application/json" \
              -d '{"target":"agentseo.dev", "location":"United States", "language":"en", "limit":25, "min_intersections":0, "max_rank_group":20, "sort_by":"threat"}'

POST/domain/intersection

Compare two domains at keyword level and prioritize shared deficits, current advantages, and target1-exclusive opportunities with rank gaps, traffic gaps, agent_workflow, and markdown_summary. Requests cost 5 credits per 100 requested keywords, minimum 5, with clickstream and extra SERP enrichment disabled.

Parameters

Name	Type	Description
target1 *	string	First domain or URL. In shared mode this is the domain being compared against target2.
target2 *	string	Second domain or URL, usually the competitor selected from /domain/competitors.
location	string	Search market (default: United States)
location_code	integer	Optional provider location code. Wins over location when provided.
language	string	Language code or name (default: en)
limit	integer	Keywords to request (5-250, default: 25)
intersections	boolean	true returns shared keywords; false returns keywords where target1 ranks and target2 does not (default: true)
min_search_volume	integer	Minimum search volume filter (default: 0)
sort_by	enum	opportunity, search_volume, traffic_gap, rank_gap, or cpc (default: opportunity)

Example

curl -X POST https://www.agentseo.dev/api/v1/domain/intersection?sync=true \
  -H "x-api-key: sk_live_..." \
  -H "Content-Type: application/json" \
              -d '{"target1":"hubspot.com", "target2":"salesforce.com", "location":"United States", "language":"en", "limit":25, "intersections":true, "min_search_volume":10, "sort_by":"opportunity"}'

POST/domain/traffic-estimate

Compare estimated organic, paid, featured-snippet, and local-pack traffic across multiple domains, subdomains, or URLs before spending deeper analysis credits. Returns footprint type, channel mix, opportunity score, agent_workflow, and markdown_summary. Requests cost 5 credits per 25 supplied targets, minimum 5.

Parameters

Name	Type	Description
targets *	string[]	Domains, subdomains, or absolute page URLs to estimate (1-100).
location	string	Search market (default: United States)
location_code	integer	Optional provider location code. Wins over location when provided.
language	string	Language code or name (default: en)
include_paid	boolean	Include paid-search traffic estimates (default: true)
include_featured_snippet	boolean	Include featured-snippet traffic estimates (default: true)
include_local_pack	boolean	Include local-pack traffic estimates (default: false)
sort_by	enum	organic_traffic, total_traffic, paid_traffic, opportunity, or target (default: organic_traffic)

Example

curl -X POST https://www.agentseo.dev/api/v1/domain/traffic-estimate?sync=true \
  -H "x-api-key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"targets":["hubspot.com","salesforce.com","zendesk.com"], "location":"United States", "language":"en", "include_paid":true, "include_featured_snippet":true, "include_local_pack":false, "sort_by":"organic_traffic"}'

POST/pages/intersection

Compare ranking pages to find shared page keywords or competitor-page keywords excluded from your pages. Returns search volume, page ranks, rank spread, traffic gap, intent, SERP features, priority, agent_workflow, and markdown_summary. Requests cost 5 credits per 100 requested keywords, minimum 5. Clickstream enrichment doubles the credit cost.

Parameters

Name	Type	Description
pages *	string[]	Absolute page URLs or wildcard URL patterns to compare. Maximum 5.
exclude_pages	string[]	Absolute page URLs or wildcard URL patterns to exclude, usually your own page group. Maximum 5.
location	string	Search market (default: United States)
item_types	string[]	organic, paid, featured_snippet, or local_pack (default: organic and featured_snippet)
limit	integer	Keywords to request, 5-100 (default: 25)
intersection_mode	enum	union or intersect (default: union). Use intersect when all supplied pages must rank for the keyword.
include_serp_info	boolean	Include SERP feature metadata for each keyword (default: false)
include_clickstream_data	boolean	Include clickstream-normalized metrics. Doubles credit cost (default: false).
min_search_volume	integer	Minimum search volume filter (default: 0)
max_rank	integer	Maximum rank for the first supplied page, 1-100 (default: 30)
sort_by	enum	opportunity, search_volume, traffic_gap, rank, or cpc (default: opportunity)

Example

curl -X POST https://www.agentseo.dev/api/v1/pages/intersection?sync=true \
  -H "x-api-key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"pages":["https://www.hubspot.com/products/crm/*","https://www.salesforce.com/crm/*"], "exclude_pages":["https://www.agentseo.dev/*"], "location":"United States", "limit":25, "intersection_mode":"union", "include_clickstream_data":false, "sort_by":"opportunity"}'

POST/backlinks/summary

Summarize backlink authority, referring domains, spam risk, broken backlinks, and link distribution signals for a domain, subdomain, or URL. Returns authority tier, risk level, recommended action type, agent_workflow, and markdown_summary. Requests cost 5 credits.

Parameters

Name	Type	Description
target *	string	Domain, subdomain, or absolute page URL to analyze.
include_subdomains	boolean	Include subdomain backlinks for domain targets (default: true)
include_indirect_links	boolean	Include indirect backlinks in the summary (default: true)
exclude_internal_backlinks	boolean	Exclude internal backlinks from external authority analysis (default: true)
backlinks_status_type	enum	live, all, or lost (default: live)
dofollow_only	boolean	Filter the request to dofollow backlinks only (default: false)
internal_list_limit	integer	Maximum items in internal distribution arrays, 1-100 (default: 10)
rank_scale	enum	one_hundred or one_thousand (default: one_hundred)

Example

curl -X POST https://www.agentseo.dev/api/v1/backlinks/summary?sync=true \
  -H "x-api-key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"target":"agentseo.dev", "include_subdomains":true, "include_indirect_links":true, "exclude_internal_backlinks":true, "backlinks_status_type":"live", "dofollow_only":false, "internal_list_limit":10, "rank_scale":"one_hundred"}'

POST/backlinks/list

Return a bounded list of actionable backlinks for a domain, subdomain, or URL. Each backlink is classified for authority protection, broken-target repair, lost-link reclaim, quality review, or outreach reference. Requests cost 5 credits per 100 requested backlinks, minimum 5.

Parameters

Name	Type	Description
target *	string	Domain, subdomain, or absolute page URL to analyze.
mode	enum	as_is, one_per_domain, or one_per_anchor (default: one_per_domain)
limit	integer	Backlinks to return, 1-100 (default: 25)
offset	integer	Offset for pagination up to 20,000 (default: 0)
backlinks_status_type	enum	live, all, or lost (default: live)
dofollow_only	boolean	Return dofollow backlinks only (default: false)
broken_only	boolean	Return broken backlinks only (default: false)
min_rank	integer	Optional minimum backlink rank, 0-100
sort_by	enum	rank, page_rank, first_seen, or lost_date (default: rank)

Example

curl -X POST https://www.agentseo.dev/api/v1/backlinks/list?sync=true \
  -H "x-api-key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"target":"agentseo.dev", "mode":"one_per_domain", "limit":25, "backlinks_status_type":"live", "dofollow_only":false, "broken_only":false, "sort_by":"rank", "rank_scale":"one_hundred"}'

POST/backlinks/anchors

Analyze backlink anchor text groups for a domain, subdomain, or URL. Returns anchor intent, risk and repair signals, priority, agent_workflow, and markdown_summary. Requests cost 5 credits per 100 requested anchor groups, minimum 5.

Parameters

Name	Type	Description
target *	string	Domain, subdomain, or absolute page URL to analyze.
limit	integer	Anchor groups to return, 1-100 (default: 25)
offset	integer	Offset for pagination up to 20,000 (default: 0)
backlinks_status_type	enum	live, all, or lost (default: live)
anchor_filter	string	Optional substring filter for anchor text
min_backlinks	integer	Optional minimum backlink count for an anchor group
min_referring_domains	integer	Optional minimum referring-domain count for an anchor group
sort_by	enum	backlinks, rank, referring_domains, spam_score, or broken_backlinks (default: backlinks)

Example

curl -X POST https://www.agentseo.dev/api/v1/backlinks/anchors?sync=true \
  -H "x-api-key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"target":"agentseo.dev", "limit":25, "backlinks_status_type":"live", "sort_by":"backlinks", "rank_scale":"one_hundred"}'

POST/backlinks/referring-domains

Analyze referring domains for a domain, subdomain, or URL. Returns domain rank, backlink and referring-page counts, spam and broken-link signals, action priority, agent_workflow, and markdown_summary. Requests cost 5 credits per 100 requested referring domains, minimum 5.

Parameters

Name	Type	Description
target *	string	Domain, subdomain, or absolute page URL to analyze.
limit	integer	Referring domains to return, 1-100 (default: 25)
offset	integer	Offset for pagination up to 20,000 (default: 0)
backlinks_status_type	enum	live, all, or lost (default: live)
domain_filter	string	Optional substring filter for referring domains
min_backlinks	integer	Optional minimum backlink count for a referring domain
min_referring_pages	integer	Optional minimum referring-page count for a referring domain
min_rank	integer	Optional minimum domain rank
sort_by	enum	rank, backlinks, referring_pages, spam_score, broken_backlinks, first_seen, or lost_date (default: rank)

Example

curl -X POST https://www.agentseo.dev/api/v1/backlinks/referring-domains?sync=true \
  -H "x-api-key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"target":"agentseo.dev", "limit":25, "backlinks_status_type":"live", "sort_by":"rank", "rank_scale":"one_hundred"}'

POST/backlinks/domain-pages

Analyze backlink-bearing pages for a domain or subdomain. Returns page URL, title, status, backlink and referring-domain counts, broken-link signals, page action priority, agent_workflow, and markdown_summary. Requests cost 5 credits per 100 requested pages, minimum 5.

Parameters

Name	Type	Description
target *	string	Domain or subdomain to analyze.
limit	integer	Pages to return, 1-100 (default: 25)
offset	integer	Offset for pagination up to 20,000 (default: 0)
backlinks_status_type	enum	live, all, or lost (default: live)
page_filter	string	Optional substring filter for page URLs
title_filter	string	Optional substring filter for page titles
status_code	integer	Optional HTTP status code filter
min_backlinks	integer	Optional minimum backlink count for a page
min_referring_domains	integer	Optional minimum referring-domain count for a page
sort_by	enum	backlinks, referring_domains, rank, spam_score, broken_backlinks, first_visited, words_count, or external_links (default: backlinks)

Example

curl -X POST https://www.agentseo.dev/api/v1/backlinks/domain-pages?sync=true \
  -H "x-api-key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"target":"agentseo.dev", "limit":25, "backlinks_status_type":"live", "sort_by":"backlinks", "rank_scale":"one_hundred"}'

POST/backlinks/competitors

Discover backlink-profile competitors for a target domain, subdomain, or page URL. Returns competitor domain, authority rank, backlink intersections, overlap score, priority, agent_workflow, and markdown_summary. Requests cost 5 credits per 100 requested competitors, minimum 5.

Parameters

Name	Type	Description
target *	string	Domain, subdomain, or absolute page URL to analyze.
limit	integer	Competitors to return, 1-100 (default: 25)
offset	integer	Offset for pagination up to 20,000 (default: 0)
min_rank	integer	Optional minimum competitor authority rank
min_intersections	integer	Optional minimum shared backlink intersections
main_domain	boolean	Return competitors at main-domain level when supported (default: true)
exclude_large_domains	boolean	Exclude very large generic domains from competitor discovery (default: true)
sort_by	enum	opportunity, rank, or intersections (default: opportunity)

Example

curl -X POST https://www.agentseo.dev/api/v1/backlinks/competitors?sync=true \
  -H "x-api-key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"target":"agentseo.dev", "limit":25, "min_intersections":3, "sort_by":"opportunity"}'

POST/backlinks/new-lost-timeseries

Track new and lost backlinks/referring domains over time. Returns movement points, totals, net changes, loss rate, strongest gain/loss periods, momentum classification, agent_workflow, and markdown_summary. Requests cost 5 credits.

Parameters

Name	Type	Description
target *	string	Domain to analyze, without protocol or www.
date_from	string	Start date in yyyy-mm-dd format. Historical data is available from 2019-01-30.
date_to	string	End date in yyyy-mm-dd format. Defaults to current provider data if omitted.
group_range	enum	day, week, month, or year (default: month)
include_subdomains	boolean	Include target subdomains in backlink movement (default: true)

Example

curl -X POST https://www.agentseo.dev/api/v1/backlinks/new-lost-timeseries?sync=true \
  -H "x-api-key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"target":"agentseo.dev", "date_from":"2026-01-01", "date_to":"2026-06-30", "group_range":"month"}'

POST/backlinks/page-intersection

Find source pages that link to competitor targets but not excluded/user targets. Returns prioritized link-gap opportunities, linked targets, quality signals, agent_workflow, and markdown_summary. Requests cost 5 credits per 100 requested source pages, minimum 5.

Parameters

Name	Type	Description
targets *	string[]	Competitor domains, subdomains, or absolute URLs to find shared source pages for. Maximum 5.
exclude_targets	string[]	Domains, subdomains, or absolute URLs to exclude, usually your own domain. Maximum 5.
limit	integer	Source pages to return, 1-100 (default: 25).
backlinks_status_type	enum	live, all, or lost (default: live)
dofollow_only	boolean	Only return dofollow source links when true.
intersection_mode	enum	partial or all (default: partial). Use all for broader scans that may take longer.
max_spam_score	integer	Optional maximum source spam score, 0-100.
sort_by	enum	rank, domain_rank, page_rank, first_seen, or last_seen (default: rank)

Example

curl -X POST https://www.agentseo.dev/api/v1/backlinks/page-intersection?sync=true \
  -H "x-api-key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"targets":["hubspot.com","salesforce.com"], "exclude_targets":["agentseo.dev"], "limit":25, "intersection_mode":"partial", "sort_by":"rank"}'

POST/backlinks/opportunity-finder

Turn supplied backlink prospects, competitor link-gap exports, and owned linkable assets into prioritized safe outreach, reclaim, repair, and digital PR actions. Requests cost 2 credits and do not call a paid backlink provider directly.

Parameters

Name	Type	Description
target *	string	Target domain, brand, or site.
prospects *	object[]	Backlink prospect/source rows. Each needs source_domain; add source_url, title, source_type, linked_competitors, topics, rank/domain_rank/page_rank, spam_score, dofollow, broken_link, or lost_link for stronger scoring.
owned_assets	object[]	Owned pages or assets that could earn links. Include url, title, page_type, topics, and linkable_reason.
campaign_goal	enum	mixed, link_gap, broken_link_building, digital_pr, resource_page, reclaim_lost_links, or protect_authority.
max_spam_score	integer	Maximum spam score allowed for outreach candidates, 0-100 (default: 35).
min_priority	enum	low, medium, or high (default: medium).

Example

curl -X POST https://www.agentseo.dev/api/v1/backlinks/opportunity-finder?sync=true \
  -H "x-api-key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"target":"agentseo.dev","campaign_goal":"link_gap","prospects":[{"source_domain":"example.org","source_url":"https://example.org/best-seo-tools","title":"Best SEO Tools","source_type":"resource_page","linked_competitors":["semrush.com","ahrefs.com"],"topics":["seo tools","seo api"],"domain_rank":72,"page_rank":58,"spam_score":3,"dofollow":true}],"owned_assets":[{"url":"https://www.agentseo.dev/docs/api-reference","title":"AgentSEO API Reference","page_type":"guide","topics":["seo api","seo tools"],"linkable_reason":"Detailed API reference for builders comparing SEO tooling."}]}'

POST/social/listen

Find web discussion evidence for a topic and return insights plus agent_workflow. This is web-wide discovery for pain points and buying signals, not native platform monitoring.

Parameters

Name	Type	Description
query *	string	Topic or keyword
platform	enum	reddit, twitter, all (default: all)
limit	integer	Max results (1-50, default: 10)

Example

curl -X POST https://www.agentseo.dev/api/v1/social/listen?sync=true \
  -H "x-api-key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"query":"agentic seo", "platform":"reddit"}'

System

GET/webhooks/endpoints

List the webhook endpoints registered for your workspace.

Example

curl https://www.agentseo.dev/api/v1/webhooks/endpoints \
  -H "x-api-key: sk_live_..."

POST/webhooks/endpoints

Create a signed webhook endpoint for async job delivery. The signing secret is returned once on create.

Parameters

Name	Type	Description
url *	string	HTTPS endpoint that will receive webhook POSTs
events	array	Any of job.completed, job.failed, project.budget_warning, or project.budget_exceeded

Example

curl -X POST https://www.agentseo.dev/api/v1/webhooks/endpoints \
  -H "x-api-key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"url":"https://hooks.example.com/agentseo","events":["job.completed","project.budget_warning","project.budget_exceeded"]}'

PATCH/webhooks/endpoints/{id}

Update a webhook endpoint in place. Use this to rotate target URLs, event subscriptions, descriptions, or to pause delivery with is_active=false.

Parameters

Name	Type	Description
id *	string	Webhook endpoint ID
url	string	New HTTPS target URL
description	string	Optional human-readable label
events	array	Any of job.completed, job.failed, project.budget_warning, or project.budget_exceeded
is_active	boolean	Set false to pause deliveries without deleting the endpoint

Example

curl -X PATCH https://www.agentseo.dev/api/v1/webhooks/endpoints/123e4567-e89b-12d3-a456-426614174000 \
  -H "x-api-key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"description":"Primary production hook","is_active":false}'

DELETE/webhooks/endpoints/{id}

Delete a webhook endpoint. This stops future deliveries to that target but does not remove historical delivery records.

Parameters

Name	Type	Description
id *	string	Webhook endpoint ID

Example

curl -X DELETE https://www.agentseo.dev/api/v1/webhooks/endpoints/123e4567-e89b-12d3-a456-426614174000 \
  -H "x-api-key: sk_live_..."

GET/webhooks/deliveries

Inspect recent webhook delivery attempts, response codes, and failure reasons.

Parameters

Name	Type	Description
limit	integer	Number of rows to return (default: 25, max: 100)
status	string	Filter by pending, delivered, or failed
endpoint_id	string	Filter to one webhook endpoint ID
project_id	string	Filter deliveries for one project, including budget alerts
event_type	string	Filter one event type such as project.budget_warning or job.completed

Example

curl https://www.agentseo.dev/api/v1/webhooks/deliveries?limit=25&project_id=client-alpha&event_type=project.budget_exceeded \
  -H "x-api-key: sk_live_..."

POST/webhooks/deliveries/{id}/retry

Retry a failed webhook delivery without re-running the underlying job.

Parameters

Name	Type	Description
id *	string	Webhook delivery ID

Example

curl -X POST https://www.agentseo.dev/api/v1/webhooks/deliveries/123e4567-e89b-12d3-a456-426614174000/retry \
  -H "x-api-key: sk_live_..."

GET/jobs/{id}

Check the status of an async job. Returns public progress, attempts, result, error, and attribution context.

Parameters

Name	Type	Description
id *	string	Job ID from 202 response

Example

curl https://www.agentseo.dev/api/v1/jobs/123e4567-e89b-12d3-a456-426614174000 \
  -H "x-api-key: sk_live_..."

GET/jobs/{id}/events

Open an SSE stream for live job updates. Emits events such as job.open, job.status, job.done, and job.failed.

Parameters

Name	Type	Description
id *	string	Job ID from a queued async request

Example

curl -N https://www.agentseo.dev/api/v1/jobs/123e4567-e89b-12d3-a456-426614174000/events \
  -H "x-api-key: sk_live_..." \
  -H "Accept: text/event-stream"