Connect your own agent to SolSEO
SolSEO will expose a small, scoped API so Claude Desktop, Claude Code, Cursor or a
script of your own can pull your rankings, movers, audit findings and reports, and add or tag
keywords, using a key you mint yourself. This page is the discovery document: fetch it with
Accept: application/json (or ?format=json)
and you get the same content as JSON.
Where it is up to
The endpoints are not live yet. Keys can be minted today, and they will start working the day
Phase 2 ships. Until then a call to the REST base or the MCP endpoint answers 404, and this page
says planned beside each.
| Phase | What | Status |
|---|---|---|
| 1 | This page, and API keys you mint yourself on the settings screen. | built |
| 2 | The read endpoints under /api/v1/my/, the OpenAPI document, llms.txt and the rate limits. | planned |
| 3 | The write endpoints: keywords, on-demand audits and reports, muting a finding. | planned |
| 4 | The remote MCP server at POST /mcp, so Claude Desktop, Claude Code and Cursor connect with a URL and a key. | planned |
Two ways in, one key
REST. Plain JSON under /api/v1/my, described by an
OpenAPI 3.1 document at /api/v1/my/openapi.json. Send the key as
Authorization: Bearer solseo_....
MCP. A remote MCP server at POST /mcp over
streamable HTTP, with the same bearer header. Add the URL and the key to your client and the
tools below appear in its tool list.
Every key is bound to your account and can see nothing outside it. A key holds only the scopes you tick, and there is no scope for billing, users, other accounts or bulk result pages: those are not offered, rather than merely hidden.
The tools
| Tool | Scope | What it does |
|---|---|---|
solseo_list_sites |
sites:read | List the sites on your account with keyword and competitor counts, last check and last crawl. |
solseo_get_site |
sites:read | One site by id: settings, counts, last check and last crawl. Another account's id answers 404. |
solseo_list_keywords |
keywords:read | Keywords on a site with the latest position, the change against yesterday and 30 days ago, tags and the working-on flag. Paged, 200 at most. |
solseo_keyword_history |
keywords:read | Daily positions for one keyword, 30 days by default and 365 at most. Reads the rollup, never a raw result page. |
solseo_add_keywords |
keywords:write | Add up to 200 keywords to a site. Idempotent, and all or nothing against the plan's cap: a batch that would pass it writes nothing and says what the limit is. |
solseo_remove_keyword |
keywords:write | Stop tracking one keyword. Soft: every position ever recorded stays. |
solseo_update_keyword |
keywords:write | Change tags, the working-on flag, the target URL or paused on one keyword. Refuses to change the text, country or device. |
solseo_movers |
keywords:read | The biggest risers and fallers on a site over 7 or 30 days, each with the plain sentence the report uses. |
solseo_findings |
audits:read | Open audit findings on a site from the latest crawl: code, severity, page count, and the reason and fix text. Muted findings only when asked for. |
solseo_health |
audits:read | The site's health score, the previous one, and when each crawl ran. |
solseo_search_console |
sites:read | Clicks, impressions, CTR and average position for 7, 28 or 90 days against the previous period, with the top queries and pages. 404 when the site has no property. |
solseo_alerts |
alerts:read | The last alert events on the account: rank drops, downtime, indexation loss, audit regressions and finished reports. |
solseo_reports |
reports:read | Reports on the account or one site, with period, status and the share URL when a share link exists. The PDF is fetched by that URL, not here. |
solseo_run_audit |
audits:write | Queue one on-demand crawl of a site. Refused on a plan without on-demand crawls, and when one is already queued. |
solseo_create_report |
reports:write | Queue an on-demand report for a site and a period. Answers the report id; the report arrives in the reports list when the worker finishes it. |
Limits, so nobody floods the hub
Per key: 60 reads and
10 writes a minute. Per account on a paid plan:
120 reads and
20 writes a minute, and
5,000 calls a day. On Free:
read-only, 30 reads a minute and
500 calls a day. Past a limit you get
429 with a Retry-After header. MCP housekeeping calls
(initialize, tools/list, ping) are not counted.
List responses carry an ETag, and history and Search Console answers are cached
for 60 seconds, so a client that asks the same question twice costs one query.
Getting a key
Sign in, open Settings, then API keys, give the
key a name, tick the scopes it needs and mint it. The key is shown once. Revoke it from the same
page whenever you like; anything still using it gets 401 from then on.