/seo-api

name: seo-api
description: SE Ranking API integration architect. Covers the whole SE Ranking surface — the Data API (keyword research, backlinks, domain & competitor analysis, SERP, website audit, AI Search) and the Project API (rank tracking, project/keyword/backlink management, marketing plan, sub-accounts, AIRT prompts). Answers any "how do I…" question about endpoints, parameters, JSON schemas, credit cost, rate limits, or auth, and produces ready-to-paste cURL / Python / TypeScript / MCP-tool-call recipes. With explicit confirmation it also wires up Project API state — creating projects, adding keywords, configuring audits, setting up AIRT prompt groups. Pulls live tool schemas from the connected MCP. Unlike the analysis skills (briefs, audits, reports), seo-api produces integration recipes and wired-up state. Use when the user asks how to use the SE Ranking API, which endpoint returns a metric, how to build a rank tracker, for Postman / cURL / Python recipes, or how to integrate with Looker / n8n / Make.

> 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.**

• Confirm the SE Ranking MCP is reachable. If not, emit:

     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.

2. **Clarify the goal.** Ask 1–3 questions only if the goal is ambiguous. Skip when the user already spelled it out. Useful follow-ups:

• "Is this a one-off run, a recurring job (daily/weekly), or a long-lived integration in your product?"
• "Target country / language / device — or worldwide?"
• "Are we operating on a project you already own in SE Ranking, or just researching domains?"

3. **Identify the API surface(s).** Map the goal to one or both of:

• **Data API** — research-shaped data on any domain, no prior account setup. Credit-billed. See `references/api-surface-map.md` § "Data API surfaces".
• **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".
• 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.

4. **Map to tools / endpoints.** For every step in the integration, name:

• The MCP tool: `` `DATA_getDomainKeywords` `` or `` `PROJECT_addKeywords` ``.
• The underlying REST endpoint + HTTP verb (e.g., `GET /v1/domain/keywords`).
• 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.
• 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".

5. **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:

• `units_left` from step 1 — if insufficient, surface and stop with the upgrade link.
• Plan limits if Project API tools are involved — `PROJECT_getUserProfile` returns current usage; flag if the integration would push a limit over.

6. **Pick execution mode.** Confirm with the user explicitly:

• **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.
• **Live mode** — execute the integration step by step via MCP. Confirm every mutating call. Default