SerpObserver APIv1 ReferenceLive

✓

The API is live. Generate an API key from Settings on the Agency plan and start making requests. Rate limit is 100 requests/minute per key. Questions? api@serpobserver.io.

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://www.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.