AutoAiSeo API & MCP

Getting started

1. In the dashboard, open the API & MCP tab and use the New key button to create a key. The key (rk_live_…) is shown only once.
2. Send it in the Authorization: Bearer header of every request.

curl -H "Authorization: Bearer rk_live_…" https://autoaiseo.example/api/v1/sites

Base URL: https://autoaiseo.example/api/v1. All responses are JSON; successful responses are returned in the data field.

Authentication and scopes

• Up to 10 active keys per account. Keys can be valid indefinitely or for 30 days, 90 days, or 1 year.
• AutoAiSeo doesn’t store the key itself, only its SHA-256 hash and visible prefix (rk_live_Ab3dEf). A lost key can’t be recovered; revoke it and create a new one.
• Keys that are revoked, expired, or belong to suspended accounts stop working immediately.
• Browser session cookies aren’t valid for the API; the key must be sent with every request.

Rate limit

60 requests per minute per key (or OAuth connection). Responses include the X-RateLimit-Limit and X-RateLimit-Remaining headers. If you exceed the limit, you get 429 and a Retry-After header that tells you how many seconds to wait.

Errors

{ "error": { "code": "not_found", "message": "Site bulunamadı" } }

Pagination

Long lists accept the page and per_page (max 100–200) parameters and return:

"pagination": { "page": 1, "per_page": 50, "total": 132, "total_pages": 3 }

Endpoints

GET /api/v1/me

Account, plan limits, this month’s usage, extra backlinks, and the scope of the key used.

GET /api/v1/sites

Your sites: id, domain, status, SEO health score, trust score, published articles, live backlinks, referring domains, 30-day change, and next article.

GET /api/v1/sites/{id}

Site overview: profile, publishing settings, article counts (by status), backlink network summary, and 30-day progress summary.

GET /api/v1/sites/{id}/progress?range=90d

Progress report. range: 30d, 90d, 180d, 365d, all.

GET /api/v1/sites/{id}/articles

Articles (paginated). Parameters: status (planned, generating, review, approved, published, failed), q (title/keyword search), page, per_page.

GET /api/v1/articles/{id}

Article: title, meta description, scores (SEO, GEO, readability), FAQ, partner backlinks, links in the body (internal/external/partner), and content. content: html (default), markdown or none.

GET /api/v1/sites/{id}/keywords

Keywords (paginated): cluster, search intent, priority, and the article targeting the keyword (article_id, article_status). Parameters: cluster, q, page, per_page.

GET /api/v1/sites/{id}/backlinks

Backlink report: credits, live/pending links, referring domains, anchor distribution, received links (paginated), and the latest links given.

GET /api/v1/sites/{id}/services

Work AutoAiSeo did for the site: totals, the last 12 months, and history (30 per page). Parameters: kind, q, page.

POST /api/v1/sites/{id}/articles read_write

Adds an article idea to the content plan (status planned). If no date is given, it’s placed on the day after the last article in the plan; AutoAiSeo writes it when that date arrives. Doesn’t use quota.

curl -X POST -H "Authorization: Bearer rk_live_…" -H "Content-Type: application/json" \
  -d '{"title":"Filtre kahve nasıl demlenir?","target_keyword":"filtre kahve demleme","angle":"Yeni başlayanlar için"}' \
  https://autoaiseo.example/api/v1/sites/12/articles

Body: title (required, 5–200), target_keyword, cluster, angle, scheduled_for (YYYY-MM-DD). Response: 201.

POST /api/v1/articles/{id}/generate read_write

Writes the article in the background (202, status generating). The same rules as the dashboard apply: it counts against your monthly quota (rewriting an article already written this month is free), and a published article can’t be rewritten. When it’s done, the status becomes review olur.

POST /api/v1/articles/{id}/publish read_write

Sends a written article to the site’s publishing destination (AutoAiSeo blog, WordPress, Shopify, Webflow, webhook) and returns the published URL.

MCP server

URL: https://autoaiseo.example/mcp — Streamable HTTP transport (JSON responses). Protocol versions: 2026-07-28 and older versions via handshake negotiation (2025-11-25, 2025-06-18, 2025-03-26).

Authenticate in one of two ways:

• OAuth — Connectors like Claude and ChatGPT open the AutoAiSeo sign-in and consent page when you add the URL; no API key needed. You can remove the connection in the dashboard under Connected apps.
• API key — for clients like Cursor, Claude Code, and VS Code, via the Authorization: Bearer rk_live_… header.

Claude

Settings → Connectors → Add custom connector, paste the MCP URL into the URL field, and click Connect.

ChatGPT

Settings → Apps & Connectors → Advanced settings: turn on developer mode there, then use Create connector to set the MCP URL and choose OAuth authentication.

Cursor (~/.cursor/mcp.json)

{
  "mcpServers": {
    "autoaiseo": {
      "url": "https://autoaiseo.example/mcp",
      "headers": { "Authorization": "Bearer rk_live_…" }
    }
  }
}

Claude Code

claude mcp add --transport http autoaiseo https://autoaiseo.example/mcp --header "Authorization: Bearer rk_live_…"

MCP tools

Tool results include a short text summary and a structured version of the same data (structuredContent). Write tools are listed only when write access is granted.

OAuth (for MCP client developers)

AutoAiSeo includes a small OAuth 2.1 authorization server that follows the MCP authorization spec.

• Redirect URIs must be https or localhost/127.0.0.1 addresses and must match exactly (any port is allowed for loopback addresses).
• Authorization codes are valid for 2 minutes and single-use; a second use revokes all tokens for that connection.
• Access tokens are valid for 1 hour, refresh tokens for 30 days. Refresh tokens rotate on every use; reusing an old refresh token closes the connection.
• Access tokens are issued only for the MCP server; the REST API requires a personal API key.
• On insufficient scope, the server returns 403 and WWW-Authenticate: Bearer error="insufficient_scope", scope="read write" header.

Privacy

The API activity log you see in the dashboard contains only the method, path, status code, duration, the key’s visible prefix (or the OAuth app’s name), and the time. Request and response bodies and IP addresses aren’t logged; the last 1,000 requests are kept per account.