API reference / REST v1
Opportunities & signals
Find opportunities, prepare briefs, and inspect social demand signals.
All paths below are relative to https://www.agentseo.dev/api/v1. Send your key in x-api-key. Set AGENTSEO_API_KEY in your environment before running the examples. IDs and results are illustrative.
Async result handling · Errors and limits · OpenAPI contract
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.
| Name | Type | Description |
|---|---|---|
targetRequired | 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) |
curl -X POST https://www.agentseo.dev/api/v1/opportunities/find?sync=true \
-H "x-api-key: $AGENTSEO_API_KEY" \
-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.
| Name | Type | Description |
|---|---|---|
keywordRequired | 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) |
curl -X POST https://www.agentseo.dev/api/v1/opportunities/brief?sync=true \
-H "x-api-key: $AGENTSEO_API_KEY" \
-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}'