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 cseo_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 cseo_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`	`/backlinks/summary`	Backlink Summary Get a backlink profile overview for a domain or page: rank (0-100), backlinks, referring domains, nofollow counts, spam score, broken backlinks, and top linking TLDs and countries.
`POST`	`/backlinks/list`	Backlinks List backlinks to a domain or page with the linking URL, anchor text, dofollow status, linking site rank, and first and last seen dates. Defaults to one link per linking site, strongest first. Set sort to newest, status to lost, or dofollow_only to true to change the list.
`POST`	`/backlinks/gaps`	Backlink Gaps Find sites that link to every listed competitor (1-20) but not to your domain, ranked by linking site rank, with backlink counts per competitor.

`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"
}

`POST` `/backlinks/summary`

{
  "target": "example.com",
  "include_subdomains": true
}

`POST` `/backlinks/list`

{
  "target": "example.com",
  "mode": "one_per_domain",
  "status": "live",
  "sort": "rank",
  "dofollow_only": false,
  "limit": 100
}

`POST` `/backlinks/gaps`

{
  "target": "example.com",
  "competitors": ["competitor-a.com", "competitor-b.com"],
  "limit": 100
}

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/url-inspection`	URL Inspection Check whether Google has indexed up to 25 URLs per call, with counts by coverage state and a row per URL. When Google provides it, inspection_result_link opens the URL inspection in Search Console, where you can manually request indexing. CalmSEO does not submit indexing requests. Results are cached for one hour. Google allows 2,000 inspections per day and 600 per minute per property. If a call cannot finish, the response keeps finished URLs and adds stopped_early with the reason and remaining_urls to send again.

`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"
}

`POST` `/gsc/url-inspection`

{
  "site_url": "sc-domain:example.com",
  "urls": ["https://example.com/", "https://example.com/pricing"]
}

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. `details` includes `credits_needed` and `credits_available`. When the balance is too low, it also includes `upgrade_url`, `plan`, and an `instruction` to show the user.
`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

POST /backlinks/summary

POST /backlinks/list

POST /backlinks/gaps