Skip to Content

REST API

PeekRank's REST API, authentication with a workspace API key, the projects endpoint, responses and errors, and why most work goes through MCP.

PeekRank's REST API is small on purpose: today it lists a workspace's projects. Everything else (rankings, history, research, AI visibility) is available to programs through the MCP server, which any MCP client or SDK can call with the same API key. If you're building an integration, start with MCP.

Authentication

Every request needs a workspace API key in the Authorization header. Owners and admins create keys in Settings → Developers & AI → API keys (see API keys).

Authorization: Bearer lk_live_…

A key acts as the person who created it and stops working if they stop being an owner or admin of the workspace. Read-only and billed keys both work here.

List projects

GET /api/v1/projects returns the workspace's active projects, newest first.

Terminal
curl -s https://app.peekrank.io/api/v1/projects \
  -H "Authorization: Bearer lk_live_…"
Response
{
  "ok": true,
  "data": {
    "projects": [
      { "id": "prj_…", "name": "Acme SEO", "domain": "acme.com", "keyword_count": 42 }
    ]
  }
}
Field
idThe project's id, the same one the MCP tools use.
nameThe project's name.
domainIts domain, or null if it has none.
keyword_countHow many keywords it tracks.

Archived projects aren't listed.

Errors

Errors come back as { "ok": false, "error": "…", "code": "…" }:

StatuscodeMeaning
401no_api_keyThe Authorization header is missing.
401bad_api_keyThe key is wrong, revoked, or its creator isn't an owner or admin any more.
403suspendedThe account or workspace is suspended.
500internalSomething went wrong on PeekRank's side. Try again.

Calling MCP from code

The MCP server speaks JSON-RPC over HTTP at https://app.peekrank.io/mcp and takes the same Authorization header. Use an MCP client library (the official SDKs exist for TypeScript, Python and other languages), connect over Streamable HTTP, then tools/list and tools/call. Every tool and its inputs: MCP tools.

Last updated on

On this page