API Documentation

The SEO AI Agent API lets you programmatically manage domains, track keywords, analyze SEO performance, and generate optimized content. All endpoints return JSON.

Base URL

https://seo-agent.net/api

Rate Limit

100 requests / minute

Format

JSON (UTF-8)

Authentication

All API requests require authentication via Bearer token. Include your API key in the Authorization header.

Authorization: Bearer YOUR_API_KEY

Get your API key from Profile → Connected Apps. The API also supports OAuth 2.0 for MCP clients.

Keep your API key secret. Do not share it in client-side code, public repositories, or URLs. If compromised, regenerate it immediately from your profile settings.

Domains

List Domains

GET/domains

Returns all domains in your active workspace with optional statistics.

Parameters

Name	Type	Required	Description
withstats	boolean	Optional	Include keyword count and analytics

Response

{
  "domains": [
    {
      "ID": 1,
      "domain": "example.com",
      "slug": "example_com",
      "niche": "Technology",
      "keywordCount": 25,
      "workspace_id": 1
    }
  ]
}

Example

curl -X GET "https://seo-agent.net/api/domains?withstats=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

Add Domain

POST/domains

Add one or more domains to your workspace.

Parameters

Name	Type	Required	Description
domains	string[]	Required	Array of domain names to add

Response

{
  "domains": [
    { "ID": 2, "domain": "newsite.com", "slug": "newsite_com" }
  ]
}

Example

curl -X POST "https://seo-agent.net/api/domains" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domains": ["newsite.com"]}'

Delete Domain

DELETE/domains?id={id}

Permanently delete a domain and all its tracked keywords, posts, and analytics data.

Parameters

Name	Type	Required	Description
id	integer	Required	Domain ID

Response

{ "success": true }

Example

curl -X DELETE "https://seo-agent.net/api/domains?id=2" \
  -H "Authorization: Bearer YOUR_API_KEY"

Keywords

List Tracked Keywords

GET/keywords?domain={slug}

Returns all tracked keywords for a domain with position history.

Parameters

Name	Type	Required	Description
domain	string	Required	Domain slug (e.g. example_com)

Response

{
  "keywords": [
    {
      "ID": 1,
      "keyword": "seo tools",
      "position": 12,
      "country": "US",
      "device": "desktop",
      "url": "https://example.com/tools",
      "lastUpdated": "2026-04-14T10:00:00Z"
    }
  ]
}

Example

curl -X GET "https://seo-agent.net/api/keywords?domain=example_com" \
  -H "Authorization: Bearer YOUR_API_KEY"

Add Keyword

POST/keywords

Add a keyword to track for a specific domain.

Parameters

Name	Type	Required	Description
keyword	string	Required	Keyword to track
domain	string	Required	Domain name
country	string	Optional	Country code (default: US)
device	string	Optional	desktop or mobile (default: desktop)

Response

{ "keyword": { "ID": 5, "keyword": "best seo tool", "position": 0 } }

Example

curl -X POST "https://seo-agent.net/api/keywords" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"keyword": "best seo tool", "domain": "example.com", "country": "US"}'

Search Console & Insights

List GSC Sites

GET/gsc/sites

Returns all verified sites from the user's connected Google Search Console account.

Response

{
  "sites": [
    { "siteUrl": "https://example.com/", "permissionLevel": "siteOwner" },
    { "siteUrl": "sc-domain:example.com", "permissionLevel": "siteOwner" }
  ]
}

Example

curl -X GET "https://seo-agent.net/api/gsc/sites" \
  -H "Authorization: Bearer YOUR_API_KEY"

Domain Insight

GET/domain-insight?domain={slug}

Get Search Console analytics: top keywords, pages, countries, and aggregate stats (clicks, impressions, CTR, position).

Parameters

Name	Type	Required	Description
domain	string	Required	Domain slug
days	integer	Optional	Date range in days (default: 30)

Response

{
  "stats": { "clicks": 1250, "impressions": 45000, "ctr": 2.78, "position": 18.5 },
  "keywords": [...],
  "pages": [...],
  "countries": [...]
}

Example

curl -X GET "https://seo-agent.net/api/domain-insight?domain=example_com&days=30" \
  -H "Authorization: Bearer YOUR_API_KEY"

Domain Keywords (GSC)

GET/domain-keywords?domain={slug}

Get all Search Console keyword data for a domain.

Parameters

Name	Type	Required	Description
domain	string	Required	Domain slug

Example

curl -X GET "https://seo-agent.net/api/domain-keywords?domain=example_com" \
  -H "Authorization: Bearer YOUR_API_KEY"

SEO Overview

GET/seo-overview?domain={slug}

SEO health overview with period-over-period comparison.

Parameters

Name	Type	Required	Description
domain	string	Required	Domain slug
days	integer	Optional	Date range (default: 30)

Example

curl -X GET "https://seo-agent.net/api/seo-overview?domain=example_com" \
  -H "Authorization: Bearer YOUR_API_KEY"

Keyword Opportunities

GET/keyword-opportunities?domain={slug}

Find quick-win keywords: striking distance (positions 5-20), low CTR, rising trends, and zero-click opportunities.

Parameters

Name	Type	Required	Description
domain	string	Required	Domain slug
days	integer	Optional	Date range (default: 30)
limit	integer	Optional	Max results (default: 20)

Example

curl -X GET "https://seo-agent.net/api/keyword-opportunities?domain=example_com&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

Competitors

List Competitors

GET/competitors?domain={slug}

Get the list of competitor domains configured for a domain.

Parameters

Name	Type	Required	Description
domain	string	Required	Domain slug

Example

curl -X GET "https://seo-agent.net/api/competitors?domain=example_com" \
  -H "Authorization: Bearer YOUR_API_KEY"

Update Competitors

PUT/competitors

Replace the competitor list for a domain.

Parameters

Name	Type	Required	Description
domain	string	Required	Domain slug
competitors	string[]	Required	Array of competitor domain names

Example

curl -X PUT "https://seo-agent.net/api/competitors" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain": "example_com", "competitors": ["competitor1.com", "competitor2.com"]}'

SEO Analysis

Analyze Content

POST/seo/analyze

Run 20+ SEO checks on content and get a score from 0-100 with detailed suggestions.

Parameters

Name	Type	Required	Description
title	string	Required	Page title
content	string	Required	HTML content body
meta_description	string	Optional	Meta description
slug	string	Optional	URL slug
focus_keywords	string[]	Optional	Target keywords

Response

{
  "score": 78,
  "checks": [
    { "name": "Title Length", "pass": true, "message": "Title is 55 characters (recommended: 30-70)" },
    { "name": "Meta Description", "pass": false, "message": "Missing meta description" }
  ],
  "suggestions": ["Add a meta description (150-160 chars)", "Add more internal links"]
}

Example

curl -X POST "https://seo-agent.net/api/seo/analyze" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "Best SEO Tools 2026", "content": "<h1>Best SEO Tools</h1><p>...</p>", "focus_keywords": ["seo tools"]}'

Posts

List Posts

GET/posts?domain={slug}

Get all posts for a domain.

Parameters

Name	Type	Required	Description
domain	string	Required	Domain slug

Example

curl -X GET "https://seo-agent.net/api/posts?domain=example_com" \
  -H "Authorization: Bearer YOUR_API_KEY"

Create or Update Post

POST/posts

Create a new post or update an existing one. Automatically runs SEO analysis and calculates score.

Parameters

Name	Type	Required	Description
domain	string	Required	Domain name
title	string	Required	Post title
content	string	Required	HTML content
id	integer	Optional	Post ID (for updates)
slug	string	Optional	URL slug (auto-generated if empty)
status	string	Optional	draft or published (default: draft)
focus_keywords	string[]	Optional	Target keywords for SEO scoring

Example

curl -X POST "https://seo-agent.net/api/posts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain": "example.com", "title": "My Article", "content": "<p>Content here</p>", "status": "draft"}'

Delete Post

DELETE/posts?id={id}

Permanently delete a post.

Parameters

Name	Type	Required	Description
id	integer	Required	Post ID

Example

curl -X DELETE "https://seo-agent.net/api/posts?id=5" \
  -H "Authorization: Bearer YOUR_API_KEY"

MCP Integration

SEO Agent provides a Model Context Protocol (MCP) endpoint for AI assistants like Claude, Cursor, and ChatGPT. The MCP server exposes 19 tools that AI can use to analyze your websites.

MCP Endpoint

POST https://seo-agent.net/api/mcp

Available Tools (19)

get_profileGet authenticated user profile

get_current_workspaceGet active workspace info

list_domainsList all domains

get_domain_insightDomain analytics & stats

get_domain_keywordsSearch Console keywords

get_domain_seo_overviewSEO health overview

list_tracked_keywordsList tracked keywords

add_tracked_keywordAdd keyword to tracking

find_keyword_opportunitiesQuick-win keywords

list_domain_competitorsList competitors

update_domain_competitorsUpdate competitor list

get_keyword_competitorsCompetitor rankings

get_competitor_historyCompetitor rank history

generate_content_briefSEO content brief

analyze_seoContent SEO analysis

list_postsList domain posts

get_postGet single post

save_postCreate/update post

delete_postDelete post

For setup instructions, see the MCP Integration Guide or the SEO Expert Skill page.

Error Codes

All errors return a JSON object with an error field.

{ "error": "Unauthorized" }

Code	Description
200	OK — Request succeeded
201	Created — Resource created successfully
400	Bad Request — Invalid parameters or missing required fields
401	Unauthorized — Missing or invalid API key
403	Forbidden — Insufficient permissions (plan limit or role)
404	Not Found — Resource does not exist
405	Method Not Allowed — Wrong HTTP method
422	Validation Error — Input failed validation
429	Rate Limited — Too many requests (wait and retry)
500	Internal Error — Server error (contact support)