SerpObserver APIv1 ReferenceIn Development

⚠

The API is not live yet. This page is a preview of the v1 reference so you can evaluate the planned surface. You can already generate an API key from Settings on the Agency plan, but endpoints do not accept requests yet. Follow the roadmap or write to api@serpobserver.io to be notified when it ships.

Authentication

The SerpObserver API uses API keys for authentication. You can generate an API key from Settings → API Keys in your dashboard. API access is available on the Agency plan.

Include your API key in the Authorization header with every request:

bash

curl https://serpobserver.io/api/v1/keywords \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

⚠

Keep your API key secret. Do not expose it in client-side code or public repositories. Rotate it immediately from Settings if you believe it has been compromised.

Keywords

List Keywords

Retrieve all keywords for a project, including their latest position data.

GET/v1/keywords?projectId={id}

json — Response

{
  "data": [
    {
      "id": "kw_01hx...",
      "keyword": "seo agency in delhi",
      "device": "desktop",
      "location": "Delhi",
      "position": 4,
      "previousPos": 7,
      "volume": 1900,
      "updatedAt": "2025-04-05T06:00:00Z"
    }
  ],
  "total": 48,
  "page": 1
}

Add Keywords

Add up to 100 keywords per request to a project.

POST/v1/keywords

json — Request body

{
  "projectId": "proj_01hx...",
  "keywords": ["seo agency delhi", "best rank tracker india"],
  "device": "desktop",
  "location": "Delhi"
}

json — Response

{ "added": 2, "skipped": 0 }

Delete a Keyword

DELETE/v1/keywords/{id}

json — Response

{ "deleted": true }

Projects

List Projects

GET/v1/projects

json — Response

{
  "data": [
    {
      "id": "proj_01hx...",
      "name": "My SEO Agency",
      "domain": "myagency.in",
      "createdAt": "2025-01-20T10:00:00Z",
      "_count": { "keywords": 142 }
    }
  ]
}

Create Project

POST/v1/projects

json — Request body

{ "name": "New Client Project", "domain": "client.co.in" }

Rankings History

Fetch the position history for a specific keyword over a date range.

GET/v1/rankings/{keywordId}?from=2025-01-01&to=2025-04-01

json — Response

{
  "keyword": "seo agency delhi",
  "history": [
    { "date": "2025-04-01", "position": 4 },
    { "date": "2025-03-25", "position": 6 },
    { "date": "2025-03-18", "position": 9 }
  ]
}

Error Codes

Code	Meaning
401	Unauthorized — missing or invalid API key.
403	Forbidden — feature not available on your current plan.
404	Not Found — the resource does not exist.
422	Unprocessable Entity — validation error in request body.
429	Too Many Requests — you've hit the rate limit (100 req/min).
500	Internal Server Error — something went wrong on our end.