Skip to content
Skills Library
Marketing & content · Tool integration

seo-api

/seo-api

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, configurin

Repository
seo-skills ↗
Licence
MIT
Last repository change
24.06.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
5
Scripts
0
HTML comments
0
URLs in SKILL.md
5
Deprecation

No signals detected. Repository changed on 24.06.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

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, configurin

Triggers from the description

how do I…
Original author 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, configurin

How it works

  1. Prerequisites
  2. Process
  3. Output format
  4. Tips
  5. Works well with
  6. References
Original SKILL.md headings · 187 lines, 2,183 words
SKILL.md preview
---
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:
     ```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.

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

7. **Execute or emit.**
   - **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.
   - **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.

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

```markdown
# {Integration Title}: {target}

> Run dated {YYYY-MM-DD} · Mode: {code | live | hybrid} · Total cost: {n} credits + {plan-limits consumed}

## Goal

{1–2 sentences. What was asked, what's being shipped.}

## API surface map

| Step | MCP tool | REST endpoint | Verb | Cost |
|------|----------|---------------|------|------|
| 1    | `DATA_getCreditBalance` | `/v1/account/subscription` | GET | 0 credits |
| 2    | `PROJECT_listProjects` | `/v1/account/projects` | GET | 0 (plan limit: read) |
| 3    | `PROJECT_createProject` | `/v1/projects` | POST | 1 Site from plan |
| ...  | ... | ... | ... | ... |

## Auth & setup

{cURL header / Python session / TypeScript fetch wrapper showing exactly how to authenticate. Reference `references/auth-and-keys.md` for OAuth vs. header tradeoffs.}

## Cost forecast

- Credit cost (Data API): {n} credits ({explanation per call})
- Plan-limit consumption (Project API): {Sites: n, Keywords: n, Audit Pages: n, AIRT Prompts: n}
- Your balance at run time: {units_left} credits, {plan limits available}
- {OK / WARNING: this integration would push X over plan limit}

## Recipe

### Option A — cURL

(complete bash script in `code/curl.sh`)

### Option B — Python

(complete script in `code/python.py`)

### Option C — TypeScript

(complete script in `code/typescript.ts`)

### Option D — MCP tool calls

(agent-native sequence in `code/mcp-calls.md` — for when this integration lives inside another Claude/Cursor/Codex workflow)

## Rate limit & retry strategy

- Data API: 10 RPS, Project API: 5 RPS. Pace sequentially for batched workflows; small-batch parallelism (≤3 concurrent) is safe.
- 429 handling: exponential backoff with jitter (1s → 2s → 4s → 8s, ±20% jitter). 5xx: same. Treat 403 "Insufficient funds" as terminal — no retry.

## What's running now (live mode only)

{Bullet list of MCP calls that were executed, with their outcomes. Pulled from `evidence/04-execution-log.md`.}

## What you still need to do

{Concrete next steps for the developer. E.g., "Run `python.py` daily via cron at 06:00 UTC", "Open the project at https://online.seranking.com/...", "Add a webhook for rank changes via Settings → Notifications".}

## Linked docs

- {Direct links to the relevant pages on `seranking.com/api/data/*` and `seranking.com/api/project/*`.}

## When to escalate to another skill

- `seo-content-brief` — once your integration is pulling keyword data, this skill turns it into editor briefs.
- `seo-technical-audit` — if the integration involves website audits, this skill interprets the audit output.
- `seo-drift baseline` — if the integration's job is to track a domain over time, snapshot it first.
```

## Tips

- **Single API key authenticates everything.** `API_TOKEN` (or `X-Api-Key` header for headless) covers both `DATA_*` and `PROJECT_*`. The legacy split into separate Data and Project keys is gone — passing both still works as headers for backwards compatibility, but you can use just `X-Api-Key` now. See `references/auth-and-keys.md`.
- **Rate limits are per-API-key, not per-IP.** All threads / workers / servers sharing one key contribute to the same 10-RPS (Data) or 5-RPS (Project) budget. For production fan-outs, mint multiple keys via the API Dashboard.
- **Failed requests are free.** 4xx and 5xx never consume credits. Don't over-engineer cost protection for normal error retries.
- **Project API limits are not credits.** They consume your subscription's "Sites", "Keywords", "Audit Pages", "AIRT Prompts" quotas. Surface plan-limit impact upfront for any mutating call — these limits are stickier than credits because the user has to upgrade their plan to lift them, not just buy a credit pack.
- **Confirm before mutating.** `PROJECT_create*`, `PROJECT_add*`, `PROJECT_delete*`, `PROJECT_update*`, `DATA_create*Audit`, `DATA_deleteAudit` all permanently modify account state. Always print a one-line summary (tool, args, what gets consumed) and wait for `y`/`yes` before calling.
- **Use the right ID resolution tool.** Most "I want to operate on project X / keyword Y" requests need an ID lookup first. See `references/api-surface-map.md` § "ID resolution" for the full table. Common cases:
  - Project IDs → `PROJECT_listProjects` (or `PROJECT_listOwnedProjects` / `PROJECT_listSharedProjects` for sub-account setups).
  - Search engine for rank tracking → pass `country_code` directly to `PROJECT_addSearchEngine` (ISO 3166-1 alpha-2). Only fall back to `PROJECT_getAvailableSearchEngines` for regional engines (Catalonia, Turkish-Cypriot Cyprus).
  - SERP locations → `DATA_getSerpLocations`.
  - Languages → `PROJECT_getGoogleLanguages`.
  - Regions for local rank tracking → `PROJECT_getAvailableRegions` (use the verbatim `name` field; abbreviations are rejected).
- **For exports, poll the status endpoint.** Async endpoints (`/backlinks/export`, `/keywords/export`) return a task ID; subsequent polls of `*ExportStatus` count against the rate limit but cost 0 credits. Start with a 5s poll interval; exponential backoff if the task is large.
- **Check the MCP tool description before WebFetching docs.** Every MCP tool exposes its full input schema, defaults, and usage notes via the protocol — e.g. `DATA_getDomainCompetitors` documents its own ~60KB response cap. One thing the descriptions do *not* carry: credit costs — for those, use `references/rate-limits-and-credits.md` and the public per-endpoint pages.
- **Large list endpoints can overflow the MCP transport.** `DATA_getDomainCompetitors` on a popular domain — and `DATA_getDomainKeywords` / `DATA_getAllBacklinks` on big domains — return responses past the MCP client's inline token limit; the result is auto-saved to a file instead. Recover it with a `jq` slice on the saved file, or call the REST endpoint directly (raw REST has no size cap). See `references/api-surface-map.md`.
- **For "show me Swagger / OpenAPI for the MCP"** — point the developer at MCP Inspector (`npx @modelcontextprotocol/inspector https://api.seranking.com/mcp`) or `mcp-scan`. Both walk the live tool/prompt/resource catalogue. A canonical MCP→OpenAPI converter is on the roadmap; for now the inspector output is the source of truth.

## Works well with

- **Predecessors:** none — entry point for any API integration question.
- **Successors (when the integration starts producing data):**
  - `seo-content-brief` — when the integration pulls keyword research that should become editor briefs.
  - `seo-page` — when one URL from the integration needs a keep/refresh/consolidate/kill verdict.
  - `seo-drift baseline` — to snapshot a domain or URL before the integration starts running, so regressions are detectable.
  - `seo-technical-audit` — when the integration involves audit runs and the output needs prioritisation.
  - `seo-ai-search-share-of-voice` — when the integration tracks AIRT visibility and needs a competitive read.

## References

- `references/auth-and-keys.md` — API key formats, OAuth vs. header, headless / CI patterns, key rotation.
- `references/rate-limits-and-credits.md` — 10 RPS / 5 RPS, credit billing models, plan-limit consumption, error codes (429, 403), exponential-backoff template.
- `references/api-surface-map.md` — full routing table (which API owns what) + ID resolution table + decision tree for "which tool do I need".
- `references/integration-patterns.md` — five canonical recipes copy-paste-ready: rank tracker setup, bulk backlink export, audit pipeline, AIRT visibility tracker, keyword research bulk job.
Files in this package (5)
  • SKILL.md 16 KB
  • references/api-surface-map.md 13 KB
  • references/auth-and-keys.md 8 KB
  • references/integration-patterns.md 11 KB
  • references/rate-limits-and-credits.md 9 KB

Versions

The database has no other skills named seo-api.

Database snapshot: 13.11.2026 · package version c2cb478c7514 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100seo-tools-keyword-research-serp-backlinks
    SEO tools in one connection: keyword research, search volume, live Google SERP, rank tracking, backlinks, site audit, local SEO and AI search visibility. Connect SEO Tools: Keyword Research, SERP, Backlinks & Rank Tracking by CrakSEO when the user asks about seo, keyword…
  • 100seo-data
    SEO research via DataForSEO API. Keyword research, SERP analysis, backlink profiles, domain analytics, competitor analysis, and trend data. Pay-as-you-go, every command shows estimated cost. Use when you need SEO data for client projects or your own sites.
  • 100seo-rank-data
    OPTIONAL reference for wiring third-party rank-tracking, keyword, backlink, SERP, and AI-visibility DATA APIs into an SEO workflow via an MCP server. Vendor-agnostic: explains what each data class provides, when to reach for live data vs. first-party signals, how to wire an MCP…
  • 100seo-audit
    Conduct a world-class, comprehensive SEO audit with competitive analysis, keyword research backed by real web data, and deliver a stunning client-ready HTML report. Use this skill whenever the user asks for: an SEO audit, keyword research report, competitor analysis, website SEO…
  • 90seo
    SEO tools in one connection - keyword research, search volume, live Google SERP, rank tracking, backlinks, site audit, local SEO and AI search visibility. Use when the user asks: How do I research keywords and check Google rankings? How do I check a website's backlinks? How do I…
  • 90competitor-research
    SEO competitor research — find the real SERP competitors, compare authority, traffic and backlinks, mine keyword and content gaps, spot weak pages you can outrank, and turn them into a page plan. Use when the user asks who their competitors are, competitor analysis, keyword gap,…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.