API reference / REST v1
Search & extraction
Search results, page extraction, and SERP analysis.
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/search
Perform a Google search with optional domain filtering. Returns raw SERP evidence plus agent_support so an agent can choose the next workflow.
| Name | Type | Description |
|---|---|---|
queryRequired | 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 |
curl -X POST https://www.agentseo.dev/api/v1/search?sync=true \
-H "x-api-key: $AGENTSEO_API_KEY" \
-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.
| Name | Type | Description |
|---|---|---|
urlRequired | string | Target URL |
format | enum | markdown, text, html (default: markdown) |
include_images | boolean | Include image extraction (default: false) |
curl -X POST https://www.agentseo.dev/api/v1/extract \
-H "x-api-key: $AGENTSEO_API_KEY" \
-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.
| Name | Type | Description |
|---|---|---|
keywordRequired | 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) |
curl -X POST https://www.agentseo.dev/api/v1/analyze/serp?sync=true \
-H "x-api-key: $AGENTSEO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"keyword":"plumbers near me", "location":"Austin, TX", "location_code":1026201, "device":"mobile"}'