CalmSEO REST API

Use the REST API to call the same SEO data tools from your own app, scripts, or scheduled jobs. Responses are compact JSON designed for programmatic use.

Base URL

https://api.calmseo.com/api/v1

Authentication

Create an API key in the CalmSEO dashboard, then pass it as a bearer token on every request.

Authorization: Bearer calmseo_your_api_key

API keys must be sent in the Authorization header. The API does not accept keys in query strings or alternate key headers.

Quickstart

curl https://api.calmseo.com/api/v1/serp/search \
  -H "Authorization: Bearer calmseo_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "keyword": "dentist in Austin",
    "location_name": "United States",
    "language_name": "English",
    "depth": 10
  }'

Response format

Successful tool calls return JSON with the tool name and data:

{
  "ok": true,
  "tool": "search_serp",
  "data": {
    "results": [],
    "credits_used": 10,
    "credits_remaining": 490
  }
}

DataForSEO-backed endpoints include credits_used and credits_remaining. Google Search Console endpoints use the connected Google account for the API key owner.

Discovery

Use discovery when you want the current API route list from the server.

Method	Path	Description
`GET`	`/health`	Check whether the CalmSEO API service is reachable.
`GET`	`/tools`	List available API tools, methods, paths, and descriptions.

SEO data endpoints

These endpoints use CalmSEO credits and return compact DataForSEO results.

Method	Path	Use
`POST`	`/serp/search`	SERP Search Run a live Google or Bing organic SERP search for a keyword, location, language, device, and depth.
`POST`	`/keywords/search-volume`	Keyword Search Volume Get Google Ads search volume, CPC, and competition for a batch of keywords.
`POST`	`/keywords/ideas`	Keyword Ideas Expand seed keywords into a DataForSEO Labs keyword research set.
`POST`	`/rankings/keywords`	Ranked Keywords Find keywords a domain, subdomain, or page URL ranks for in Google.
`POST`	`/audits/page`	Page Audit Run a single URL on-page SEO audit using DataForSEO Instant Pages.

`POST` `/serp/search`

{
  "keyword": "dentist in Austin",
  "location_name": "United States",
  "language_name": "English",
  "search_engine": "google",
  "device": "desktop",
  "depth": 10
}

`POST` `/keywords/search-volume`

{
  "keywords": ["seo consultant", "technical seo audit"],
  "location_name": "United States",
  "language_name": "English"
}

`POST` `/keywords/ideas`

{
  "keywords": ["roof repair"],
  "location_name": "United States",
  "language_name": "English",
  "limit": 50
}

`POST` `/rankings/keywords`

{
  "target": "example.com",
  "location_name": "United States",
  "language_name": "English",
  "limit": 50
}

`POST` `/audits/page`

{
  "url": "https://example.com/pricing"
}

Google Search Console endpoints

These endpoints require the API key owner to connect Google Search Console in CalmSEO first.

Method	Path	Use
`GET`	`/gsc/sites`	List GSC Sites List Google Search Console properties connected to the CalmSEO account.
`POST`	`/gsc/search-analytics`	Search Analytics Query clicks, impressions, CTR, and average position with custom dimensions and filters.
`POST`	`/gsc/top-queries`	Top Queries Get top Search Console queries for a property by clicks, impressions, CTR, and average position.
`POST`	`/gsc/top-pages`	Top Pages Get top Search Console pages for a property by clicks, impressions, CTR, and average position.
`POST`	`/gsc/page-queries`	Page Queries Get Search Console queries that drove impressions and clicks for one page URL.
`GET`	`/gsc/sitemaps` `?site_url=sc-domain%3Aexample.com`	List Sitemaps List submitted Google Search Console sitemaps for a connected property.

`POST` `/gsc/search-analytics`

{
  "site_url": "sc-domain:example.com",
  "start_date": "2026-05-01",
  "end_date": "2026-05-31",
  "dimensions": ["query", "page"],
  "type": "web",
  "row_limit": 100
}

`POST` `/gsc/top-queries`

{
  "site_url": "sc-domain:example.com",
  "start_date": "2026-05-01",
  "end_date": "2026-05-31",
  "row_limit": 50,
  "type": "web"
}

`POST` `/gsc/top-pages`

{
  "site_url": "sc-domain:example.com",
  "start_date": "2026-05-01",
  "end_date": "2026-05-31",
  "row_limit": 50,
  "type": "web"
}

`POST` `/gsc/page-queries`

{
  "site_url": "sc-domain:example.com",
  "page_url": "https://example.com/pricing",
  "start_date": "2026-05-01",
  "end_date": "2026-05-31",
  "row_limit": 50,
  "type": "web"
}

Errors

Errors use conventional HTTP status codes and a stable JSON shape:

{
  "ok": false,
  "error": {
    "code": "invalid_request",
    "message": "Request validation failed.",
    "details": {
      "issues": [
        {
          "path": "keyword",
          "message": "Required"
        }
      ]
    }
  }
}

Status	Code	Meaning
`400`	`invalid_json`, `invalid_request`	The request body or parameters could not be parsed.
`401`	`unauthorized`	The API key is missing, invalid, or rotated.
`402`	`insufficient_credits`	The account does not have enough credits for the request.
`429`	`rate_limited`	A Search Console rate limit was reached.
`502`	`dataforseo_error`	The upstream SEO data provider returned an error.

Notes

SERP searches support plain keywords. Advanced search operators such as site:, inurl:, and intitle: are rejected.
Search Console dates use YYYY-MM-DD format. Search Console data is usually delayed by 2-3 days.
Use GET /tools if you need to discover routes dynamically.

CalmSEO REST API

Base URL

Authentication

Quickstart

Response format

Discovery

SEO data endpoints

POST /serp/search

POST /keywords/search-volume

POST /keywords/ideas

POST /rankings/keywords

POST /audits/page