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.	built
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. Send the key as Authorization: Bearer solseo_....

If you are pointing a language model at this, give it AGENTS.md: every address, every setting, and what each refusal means, including the one that catches people out (a 404 means "not yours, or not there" and never "it was deleted"). llms.txt is the short index that points at both.

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. A day with no check is absent from the array rather than null.
`solseo_movers`	keywords:read	The biggest risers and fallers on a site over 7 or 30 days.
`solseo_health`	audits:read	The site's health score, the previous one, and when each audit ran.
`solseo_findings`	audits:read	Open findings on a site from the latest audit: code, severity, page count, and the reason and fix text. Muted findings only when asked for.
`solseo_search_console`	sites:read	Clicks, impressions, CTR and average position over 7, 28 or 90 days against the period before it. 404 when the site has no property connected.
`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, whether a share link exists and its hint. The address of a share link is never returned: only its digest is stored, so nothing can reconstruct it.
`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_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_remove_keyword`	keywords:write	Stop tracking one keyword. Soft: every position ever recorded stays.
`solseo_run_audit`	audits:write	Queue one on-demand audit of a site. Refused on a plan without on-demand audits, when one already ran for that site today, and when the account has spent its allowance for the last seven days, which answers the limit, the usage and when to try again.
`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 a minute. Per account on a paid plan: 120 a minute and 5,000 in a rolling 24 hours, not a calendar day. On Free: 30 a minute and 500. Past a limit you get 429 with a Retry-After header and the three X-RateLimit headers.

Two keys on one account share the account's window, because it is an account limit rather than a per-key limit with a bigger number on it.

Every answer carries an ETag. Send it back as If-None-Match and an unchanged answer is a 304 with no body, which still counts against the limit. History, movers, findings and Search Console answers are also held for 60 seconds, so asking the same question twice costs one query.

Getting a key

Sign in, open the API page in your dashboard, 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.