MCP and API

REST API reference

Read and update your SEOForge projects, articles, content plan, rankings and Google data over HTTPS.

Copy page for your AI assistant

The REST API gives your own scripts and tools the same data and actions as the MCP server. It uses the same API keys.

https://www.seoforge.ai/api/v1

Your first request#

curl https://www.seoforge.ai/api/v1/projects \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "data": [
    {
      "id": "8c1d…",
      "name": "Acme",
      "website": "https://acme.com",
      "primary_language": "English",
      "is_paid": true,
      "role": "owner"
    }
  ]
}

Use a project's id in the other endpoints.

Requests and responses#

• Send JSON bodies with Content-Type: application/json.
• Dates use YYYY-MM-DD.
• A successful response is 200 with the result under data.
• Responses aren't cached (Cache-Control: no-store).

Errors#

Every error has the same shape:

{
  "error": {
    "code": "project_not_found",
    "message": "Project not found."
  }
}

If Google Analytics isn't connected for a project, the analytics endpoints return { "connected": false, "note": "…" } rather than an error.

Pagination#

List endpoints take limit and offset and return:

{ "data": { "total": 132, "limit": 25, "offset": 0, "results": [] } }

limit goes up to 100. It defaults to 25 for articles and 50 for the content plan.

Endpoints#

Endpoints marked Write need a Read & write key.

Projects#

Articles#

content_length is one of 1000-2000, 2000-3000, 3000-4000 or 4000-5000 words.

Content plan#

Rank tracking#

Search Console#

compare_to is previous_period or previous_year.

Google Analytics#

Jobs#

Toolset tools#

The tool reference lists each tool. The core MCP tools, like list_projects, aren't available here; use the endpoints above instead.

curl -X POST https://www.seoforge.ai/api/v1/tools/find_striking_distance \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"project_id": "YOUR_PROJECT_ID"}'

Tool responses include meta.cost, which shows what the call would cost in credits. Paid data is free during the beta, up to a daily limit.

Long-running jobs#

Generating an article, refreshing one, running a site audit and batch search lookups take minutes, so they return a job_id straight away. Poll the job until it finishes:

curl https://www.seoforge.ai/api/v1/jobs/JOB_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

While a job runs, the response includes a stage. For articles, that's the current writing step. Article generation usually takes several minutes, and a refresh takes 1–3 minutes. Polling every 15–30 seconds is plenty. There are no completion callbacks.

Rate limits#

60 requests per minute per key. Going over returns 429 rate_limited with Retry-After: 60. See API keys and limits for the rest.