# REST API (/api/rest-api)

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](/ai/connect/), 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](/ai/access/#api-keys)).

```text
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.

```bash title="Terminal"
curl -s https://app.peekrank.io/api/v1/projects \
  -H "Authorization: Bearer lk_live_…"
```

```json title="Response"
{
  "ok": true,
  "data": {
    "projects": [
      { "id": "prj_…", "name": "Acme SEO", "domain": "acme.com", "keyword_count": 42 }
    ]
  }
}
```

| Field | |
|---|---|
| `id` | The project's id, the same one the MCP tools use. |
| `name` | The project's name. |
| `domain` | Its domain, or `null` if it has none. |
| `keyword_count` | How many keywords it tracks. |

Archived projects aren't listed.

## Errors

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

| Status | `code` | Meaning |
|---|---|---|
| 401 | `no_api_key` | The `Authorization` header is missing. |
| 401 | `bad_api_key` | The key is wrong, revoked, or its creator isn't an owner or admin any more. |
| 403 | `suspended` | The account or workspace is suspended. |
| 500 | `internal` | Something 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](/reference/mcp-tools/).