Serpel REST API reference

What is the base URL of the Serpel API?

All endpoints live under https://serpel.app/api/v1. Paths in this reference are relative to it, so /projects means https://serpel.app/api/v1/projects. Requests and responses use JSON. Send Content-Type: application/json with a body. GET https://serpel.app/api/v1 returns a machine-readable index of the endpoints without authentication, and GET https://serpel.app/api/health returns the service status.

How do you authenticate with the API?

Send an API token as a bearer token. Tokens start with vsk_. Create one in the dashboard under Settings, API tokens, with serpel tokens create or with POST /tokens.

GET /api/v1/projects HTTP/1.1
Host: serpel.app
Authorization: Bearer vsk_your_token

• A token can only call endpoints whose scope it has. Without it, the API answers with 403 forbidden.
• The project role still applies: viewers read, editors change, owners manage members and delete the project.
• The dashboard uses a session cookie instead of a token. Cookie requests that change data must come from the Serpel origin.
• OAuth access tokens issued to MCP clients only work at the MCP server. The REST API rejects them with 403 forbidden.

Which scopes can an API token have?

Serpel has 18 scopes. Choose the smallest set that your integration needs.

Restrict a token to projects

A token can be limited to a list of projects with projectIds. Such a token sees only those projects. A project outside the list answers with 404 not_found, as if it did not exist, and lists leave it out. Tokens can also expire after 1 to 365 days.

curl -X POST https://serpel.app/api/v1/tokens \
  -H "Authorization: Bearer $SERPEL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "CI crawl", "scopes": ["projects:read", "audit:read", "audit:write"], "projectIds": ["0b6f0f0e-6d1a-4c8e-9a53-4f9d2d7b8a10"], "expiresInDays": 90}'

In the response, token holds the metadata and secret holds the token itself. The secret is shown exactly once. Creating tokens needs a token with all permissions. A token restricted to projects can only create tokens for its own projects.

What do responses and pagination look like?

{ "data": { } }

{ "data": [ ], "pagination": { "limit": 50, "offset": 0, "total": 123 } }

Single objects come in data. Lists add pagination. Lists accept limit (1 to 200, default 50), offset (from 0) and usually q to search. Every response carries an X-Request-ID header. You can send your own X-Request-ID (up to 128 letters, digits, ., _, : and -) and quote the value when you contact support.

How does the API report errors?

{
  "error": {
    "code": "validation_error",
    "message": "Enter a domain.",
    "details": [{ "path": "domain", "message": "Enter a domain." }]
  }
}

What are the API rate limits?

When you exceed a limit, the API answers with HTTP 429 and rate_limited. Wait for the seconds in the Retry-After header, then continue. The MCP server has its own limit, described in the Claude Code guide.

How do idempotency keys work?

POST /keywords/research and POST /keyword-lists/{id}/refresh use credits and answer synchronously. Add an Idempotency-Key header with up to 200 letters, digits and the characters ., _, : and - to make a retry safe. A repeated request with the same key does not call the data provider again and does not book credits again. Without the header, the server generates a random key, which protects nothing on a retry. The CLI creates a key for you and accepts --idempotency-key.

How do credits work in the API?

Reading data is free. These operations use credits, at the prices of the dashboard:

Estimate a cost first with POST /billing/estimate. It needs billing:read, books nothing and returns minCredits, maxCredits and a breakdown. Supported operations are rankCheck, aiCheck, keywordResearch, keywordListRefresh, keywordMetrics, crawl and monitoring.

curl -X POST https://serpel.app/api/v1/billing/estimate \
  -H "Authorization: Bearer $SERPEL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"operation": "rankCheck", "params": {"keywordCount": 20, "depth": 50}}'

If the balance is too low for an operation, the API answers with HTTP 402.

{
  "error": {
    "code": "insufficient_credits",
    "message": "The available credits balance isn’t sufficient for this operation.",
    "details": { "balance": 3, "available": 3, "required": 12 }
  }
}

Which endpoints does the REST API have?

The groups below follow the index that GET /api/v1 returns. Path parameters appear in braces. Methods in one row share the path. The scope line above each table names the scopes the endpoints need.

Authentication

These endpoints serve the sign-up and sign-in screens of the dashboard and need no token. The Google endpoints are browser redirects, not JSON calls.

Free tools

These endpoints need no token. They share one limit per IP address instead: 20 requests per 10 minutes and 200 per day. GET results are cached for a short time: 1 minute for the schema validator and the redirect checker, 5 minutes for the sitemap checker and 10 minutes for the robots.txt check.

Account

GET /me works with any valid token. Changing the profile and using /tokens need a token with all permissions. /account/export, /account/delete, /account/password/set and /account/identities/google need a dashboard session, not an API token.

Billing

Reading needs billing:read. Checkouts and changes need billing:write and the workspace owner role.

MCP and connected apps

These endpoints need a dashboard session, or a token with all permissions for the two read and disconnect endpoints.

Projects

projects:read to read, projects:write to create and change. Changing a project needs the editor role, deleting it and managing members the owner role.

Audit

audit:read to read, audit:write to start crawls.

Keywords and rankings

keywords:read and keywords:write for research and lists, rankings:read and rankings:write for tracked keywords and competitors. Research and list refreshes accept an Idempotency-Key header.

AI visibility and monitoring

rankings:read and rankings:write for AI visibility and monitoring runs, projects:read and projects:write for reports, recipients and webhooks.

Account integrations

projects:read to read, projects:write to connect, map and disconnect.

Search data

projects:read to read, projects:write to connect and disconnect.

Web analytics

projects:read to read, projects:write to connect and change.

Recommendations and codebase

recommendations:read and recommendations:write, codebase:read and codebase:write.

Tasks and jobs

tasks:read and tasks:write for tasks. Jobs follow the scope of their type: audit:read for crawls, rankings:read for the other jobs.

More endpoints

These endpoints exist as well and are used by the CLI, but the index does not list them.

What do complete API examples look like?

The examples assume that SERPEL_TOKEN holds a token with the scopes named in each step. The responses are abridged to the fields you need next, and their values are illustrative. The real responses contain more fields.

Create a project

Needs projects:write. The API returns HTTP 201. If you already have a project for the domain, it answers with 409 conflict and the ID of the existing project in details.existingProjectId.

curl -X POST https://serpel.app/api/v1/projects \
  -H "Authorization: Bearer $SERPEL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"domain": "example.com", "name": "Example", "country": "US", "language": "en"}'

{
  "data": {
    "id": "0b6f0f0e-6d1a-4c8e-9a53-4f9d2d7b8a10",
    "name": "Example",
    "domain": "example.com",
    "country": "US",
    "language": "en",
    "role": "owner"
  }
}

Start a crawl and read the issues

Needs audit:write to start and audit:read to follow the job. The crawl runs in a worker, so the API answers with 202 and a job. If a crawl is already running, you get that crawl back with HTTP 200 and alreadyRunning: true. Poll GET /jobs/{id} until status is succeeded, failed or cancelled, then read the issues. maxPages can be 1 to 1000.

curl -X POST https://serpel.app/api/v1/projects/$PROJECT_ID/crawls \
  -H "Authorization: Bearer $SERPEL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"maxPages": 200}'

{
  "data": {
    "crawl": {
      "id": "7d2a4c1e-3b9f-4e0a-8c55-2f61b0a9d3e4",
      "status": "queued",
      "maxPages": 200,
      "pagesCrawled": 0
    },
    "job": {
      "id": "c41e8f27-5a6d-4b13-9d70-e8a2f4b6c915",
      "type": "crawl",
      "status": "queued"
    },
    "alreadyRunning": false
  }
}

curl https://serpel.app/api/v1/jobs/$JOB_ID \
  -H "Authorization: Bearer $SERPEL_TOKEN"

curl https://serpel.app/api/v1/projects/$PROJECT_ID/issues \
  -H "Authorization: Bearer $SERPEL_TOKEN"

Research keywords

Needs keywords:write and uses credits. A keyword research costs 8 credits plus 4 credits per block of 50 results, so 20 results cost 12 credits. The Idempotency-Key makes a retry safe. credits.charged and credits.balance show what the call cost and what is left.

curl -X POST https://serpel.app/api/v1/keywords/research \
  -H "Authorization: Bearer $SERPEL_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: research-cold-brew-2026-10-10" \
  -d '{"mode": "keyword", "keyword": "cold brew concentrate", "country": "US", "language": "en", "limit": 20}'

{
  "data": {
    "runId": "5e9b7a30-1c4d-4f82-b6a1-0d3c8e2f7a46",
    "mode": "keyword",
    "query": "cold brew concentrate",
    "country": "US",
    "language": "en",
    "cached": false,
    "items": [
      {
        "keyword": "cold brew concentrate",
        "relation": "seed",
        "searchVolume": 2900,
        "cpc": 1.45,
        "keywordDifficulty": 38,
        "intent": "commercial"
      }
    ],
    "credits": {
      "charged": 12,
      "balance": 488
    }
  }
}

Read rankings

Needs rankings:read. Each tracked keyword has its latest check and a change against the previous one; a positive change means the keyword moved up. A position of null with status ok means the page was not found within the checked depth.

curl "https://serpel.app/api/v1/projects/$PROJECT_ID/rankings?limit=2&q=cold%20brew" \
  -H "Authorization: Bearer $SERPEL_TOKEN"

{
  "data": [
    {
      "id": "a3f1c9d2-6b8e-4d57-9c20-7e4b1a5d8f03",
      "keyword": "cold brew concentrate",
      "country": "US",
      "language": "en",
      "device": "desktop",
      "searchVolume": 2900,
      "latest": {
        "checkedAt": "2026-10-09T06:00:12.000Z",
        "depth": 50,
        "position": 11,
        "url": "https://example.com/cold-brew-concentrate",
        "status": "ok"
      },
      "change": 3
    }
  ],
  "pagination": { "limit": 2, "offset": 0, "total": 1 }
}