seo-api

Live with the SE Ranking MCP at https://api.seranking.com/mcp. Tool schemas are introspected live; this skill never relies on a frozen snapshot of the API surface.

SE Ranking API Integration Architect

Help developers ship real integrations against the SE Ranking SEO Data API and Project API. The deliverable is either a code recipe (ready-to-paste cURL / Python / TypeScript / MCP-tool-call sequence) or live wiring of Project API state (create projects, add keywords, configure audits, set up AIRT prompts), or both. The skill knows the entire 195-tool surface, the credit and rate-limit cost of every call, and the canonical setup story for every major MCP client.

Prerequisites

• SE Ranking MCP connected at https://api.seranking.com/mcp. Single API key authenticates both DATA_* and PROJECT_* tools through the unified gateway. If /mcp doesn't show se-ranking, the skill emits the install command and stops — see references/auth-and-keys.md.
• (Optional) WebFetch for fetching deep guides at seranking.com/api/data/ and seranking.com/api/project/ when the request needs prose beyond JSON Schema.
• User provides: an integration goal in plain language (e.g., "build a rank tracker for client X", "pull all backlinks for these 50 domains into BigQuery weekly", "configure an audit + AIRT prompts for a new project"). The skill interviews only when the goal is ambiguous.

Process

1. Preflight.
2. Confirm the SE Ranking MCP is reachable. If not, emit:

``bash claude mcp add --transport http se-ranking https://api.seranking.com/mcp ` and stop. See references/auth-and-keys.md for OAuth vs. X-Api-Key` header tradeoffs and headless / CI patterns.

• Call DATA_getSubscription (0 credits). Record units_left, plan status, expiration — units_left is the figure to forecast against, and it gets printed in the cost forecast in step 5. Optionally also call DATA_getCreditBalance for its { limit, used } view — but the two are not aliases: they report different remaining-credit numbers that do not reconcile (an ~8.6M gap is normal), so treat getSubscription.units_left as the source of truth.

1. Clarify the goal. Ask 1–3 questions only if the goal is ambiguous. Skip when the user already spelled it out. Useful follow-ups:
2. "Is this a one-off run, a recurring job (daily/weekly), or a long-lived integration in your product?"
3. "Target country / language / device — or worldwide?"
4. "Are we operating on a project you already own in SE Ranking, or just researching domains?"

1. Identify the API surface(s). Map the goal to one or both of:
2. Data API — research-shaped data on any domain, no prior account setup. Credit-billed. See references/api-surface-map.md § "Data API surfaces".
3. Project API — operations on the user's own SE Ranking projects (rank tracking, audits, AIRT, backlink groups, marketing plan, sub-accounts). Subscription-limit-billed, not credit-billed. Requires Business or Enterprise plan. See references/api-surface-map.md § "Project API surfaces".
4. Many real integrations span both — e.g., a rank-tracker setup uses PROJECT_createProject + PROJECT_addKeywords + PROJECT_runPositionCheck, then reports use DATA_getDomainKeywords for the same domain.

1. Map to tools / endpoints. For every step in the integration, name:
2. The MCP tool: ` DATA_getDomainKeywords or PROJECT_addKeywords `.
3. The underlying REST endpoint + HTTP verb (e.g., GET /v1/domain/keywords).
4. The credit cost (Data API) or limit consumed (Project API). Source costs from references/rate-limits-and-credits.md and the per-endpoint pages at seranking.com/api/data/* — MCP tool description fields carry input schemas and usage notes but not credit costs.
5. If a tool needs an ID the user didn't supply (project ID, search engine ID, geo region name, language code), insert the prerequisite list or available call before it. See references/api-surface-map.md § "ID resolution".

1. Forecast cost. Sum credit cost across all Data API calls. For Project API calls, surface plan-limit impact (e.g., "this consumes 1 Site + 50 Keywords + ~500 Audit Pages from your plan"). Compare against:
2. units_left from step 1 — if insufficient, surface and stop with the upgrade link.
3. Plan limits if Project API tools are involved — PROJECT_getUserProfile returns current usage; flag if the integration would push a limit over.

1. Pick execution mode. Confirm with the user explicitly:
2. Code mode — emit ready-to-paste cURL, Python (requests), TypeScript (fetch), and MCP-tool-call variants. The developer runs them. Default for read-only research, recurring jobs the user wants to own, and anything they want to deploy outside their Claude session.
3. Live mode — execute the integration step by step via MCP. Confirm every mutating call. Default for one-off Project API setup (new project, add keywords, configure audit, set up AIRT prompt group, etc.) where the user wants the state to exist by the end of this conversation.
4. Hybrid — wire up the one-time setup live, emit code for the recurring workload (e.g., "I created the project and added the 50 keywords for you; here's the daily-run Python script to pull positions and write them to BigQuery").

1. Execute or emit.
2. Code mode — write code/curl.sh, code/python.py, code/typescript.ts, code/mcp-calls.md. Each file is a complete runnable example, not a fragment. Include error handling for 429 (rate limit) and 403 (insufficient credits). See references/integration-patterns.md for canonical pattern snippets.
3. Live mode — for each mutating call (PROJECT_create*, PROJECT_add*, PROJECT_delete*, PROJECT_update*, DATA_createStandardAudit, DATA_createAdvancedAudit, etc.), print a single-line confirmation:

`` About to call PROJECT_createProject(domain="acme.com", name="ACME Inc — Rank Tracker", country="us"). Consumes: 1 "Site" from your subscription. Proceed? [y/N] ` Wait for explicit y / yes. On anything else, fall back to code mode and emit the equivalent code instead of executing. Read-only calls (DATA_get*, DATA_list*, PROJECT_get*, PROJECT_list*) run without confirmation. Log every call to evidence/03-execution-log.md` with timestamp, args, response status.

1. Synthesise RECIPE.md. Always written, regardless of mode. The deliverable a developer reads to understand what was built or how to build it. See output format below.

Output format

Folder seo-api-{slug}-{YYYYMMDD}/ where {slug} is a kebab-case summary of the goal (e.g., acme-rank-tracker, bulk-backlinks-bigquery).

seo-api-{slug}-{YYYYMMDD}/
├── RECIPE.md                       (primary deliverable — what was built or how to build it)
├── code/
│   ├── curl.sh                     (cURL one-liners + multi-step bash)
│   ├── python.py                   (idiomatic requests-based script)
│   ├── typescript.ts               (fetch + zod-validated responses)
│   └── mcp-calls.md                (MCP-tool-call sequence — same workflow, agent-native)
└── evidence/
    ├── 01-preflight.md             (credit balance, subscription status, MCP connectivity check)
    ├── 02-cost-forecast.md         (per-call cost breakdown, plan-limit deltas, total)
    ├── 03-ids-resolved.md          (Project API / search-engine IDs, geo codes resolved upfront — omit if none needed)
    └── 04-execution-log.md         (every MCP call executed, with args + status — omit in pure code mode where nothing ran)

Top-level: RECIPE.md + code/. The evidence/ folder preserves the reasoning trail; auditors lean on 02-cost-forecast.md and the execution log. 03 and 04 are conditional — a run with no ID lookups and no executed calls (pure code-mode advice) ships just 01 + 02.

RECIPE.md follows this shape:

# {