rankscale-api-skill

Rankscale API skill

An Agent Skill that teaches your AI coding agent to query the Rankscale AI brand-visibility REST API on demand — so an SEO or marketing professional can pull data into reports, tables, and charts without clicking through the dashboard.

Ask your agent things like:

"How is my brand doing this week?" "Show me the citation sources for brand X." "What's my Rankscale credit balance and runway?" "List my tracked brands." "Run every prompt in topic X 20 times."

…and get clean tables back, with the raw JSON saved alongside for follow-ups.

Works with most agentic coding tools

This is a plain-markdown skill (a SKILL.md plus reference files) that drives the REST API with curl. It's model- and provider-agnostic — nothing in it is tied to a specific AI vendor. It works with any agentic harness that can read a skill/ instructions file and run shell commands, including:

• Claude Code (native Agent Skills support)
• Cursor
• OpenAI Codex
• Windsurf
• Gemini CLI
• GitHub Copilot (agent mode)

If your tool doesn't auto-load skills, just point it at SKILL.md and it'll follow the instructions there.

What it can do

• Reporting — visibility, sentiment, mentions, citations, avg. position, detection rate, top-3 rate over any time window
• Brand Rank (by Visibility) — your brand's computed rank vs. competitors, overall or per topic / engine / query
• Citations — which third-party sources AI models cite for your tracked terms
• Sentiment — positive / neutral / negative breakdowns
• Search-term reports — per-query performance
• Workspace management — list / create / edit brands, topics, and search terms (writes always ask for confirmation)
• Bulk runs — run every search term in a topic N times, all in parallel, with a bundled script (scripts/bulk_run.js) that starts with a dry run showing the runs and the estimated credit cost
• Credits — balance and runway estimate

Usage examples

A worked walkthrough of the skill in action — real questions and the tables it produces — is here: Rankscale skill examples (from a July 2026 webinar).

Requirements

• An agentic coding tool that can read a skill file and run shell commands (see the list above).
• A shell with curl available (JSON parsing uses whatever's on hand — node, jq, or python).
• Node.js 18 or later, only for the bulk-run script.
• A Rankscale account with REST API access enabled (Agency Growth or Enterprise plan). If your API key starts with rk_ you're set; otherwise ask the Rankscale team to enable REST API access.

Install

See INSTALL.md for the full setup. In short, for Claude Code:

git clone https://github.com/bojan-basrak/rankscale-api-skill.git \
  ~/.claude/skills/rankscale-api-skill

For other tools, place the folder wherever that tool loads skills or custom instructions from (or just open the repo and point your agent at SKILL.md).

This repo is the canonical source. Any installed copy is a mirror. The skill tells the agent to git pull --ff-only its own folder before each use, so a clone kept as a git checkout stays current on its own — git clone it (don't download a zip) so that self-update works.

Then set your API key as an environment variable:

# macOS / Linux — add to ~/.bashrc or ~/.zshrc
export RANKSCALE_API_KEY="rk_your_key_here"

# Windows PowerShell (persistent) — open a new shell afterward
setx RANKSCALE_API_KEY "rk_your_key_here"

Layout

Limitations

• Paid plans only. REST API access is available on Rankscale's Agency Growth and Enterprise plans. If you don't have an rk_ key, the skill can't do anything — ask the Rankscale team to enable it.
• The API may change without notice. Rankscale now publishes an official OpenAPI 3.1.0 reference for the Metrics API (help center → Metrics API, signed-in only); this skill is reconciled against it and filled in with hands-on probing where the spec is loose or silent. Last reconciled against the 2026-07-29 docs revision, with live field-testing passes on 2026-08-07 (corrected the brandNotFound flag and the API-key format, added several undocumented response fields), 2026-08-26 (found that timeFrame presets disagree with ISO windows, that unfiltered competitorMetrics[] is truncated, and documented the groupMeta field), and 2026-09-22 (corrected the /run behavior: it blocks until the run finishes, so bulk runs must fire concurrently; runs draw on rankCredits, not analysisCredits). Endpoints, field names, engine IDs, and behaviors do shift — if calls start failing or returning odd shapes, the skill likely needs updating. The quirks it documents (strict camelCase params, exclusive end dates, POST-not-GET reporting) are current-as-of-testing, not guaranteed-stable.
• No live validation here. Nothing in this repo is tested against your account. Always sanity-check that returned time windows and numbers match what you asked for before trusting a report.
• Rate limits apply. 200 requests/min per key; the skill caches and batches, but heavy ad-hoc use can hit the ceiling.

Security

The skill reads the API key from the RANKSCALE_API_KEY environment variable (the bulk-run script can instead read it from a file you name with --key-file) and never prints it or writes it to disk. No credentials are stored in this repository. Don't commit your key.

Disclaimer

This is an unofficial skill. I am not affiliated with Rankscale — just a power-user of their tool, a beta-tester, and a friend of the Rankscale team.

The official Rankscale API documentation is not public; it's available only to signed-in users, in the help center (they'll likely change that soon). This skill is reconciled against that reference but is not a substitute for it.

I'm an SEO & business-growth consultant, not a developer. I wouldn't even call myself a "vibe coder" — I barely read the files for this skill, which were created by Claude Opus 4.8. So use it at your own risk and discretion. I offer no guarantees and no support.

License

MIT.