NOVA SEO API

Docs › NOVA › NOVA SEO

API

Call NOVA SEO from your own code: one address per tool, JSON in, JSON out.

Get a key

In NOVA, open Manage Site, SEO, Use NOVA SEO anywhere, give the key a name and press New key. Copy it at once: it starts with nseo_ and is shown only this one time. Keep it in a secret store or an environment variable, never in your site's code.

Addresses

GET /api/seo/v1/toolsEvery tool, what it does, its inputs and whether it costs credits. No key needed.
POST /api/seo/v1/<tool>Run one tool. Send a JSON object with its inputs; get a JSON object back.
POST /api/seo/mcpThe same tools over MCP (JSON-RPC 2.0), for MCP clients.

All addresses start with https://runnova.ai. Send the key on every call as Authorization: Bearer nseo_....

First calls

bash
export NOVA_SEO_KEY=nseo_your_key

# Your sites
curl -s https://runnova.ai/api/seo/v1/list_sites \
  -H "Authorization: Bearer $NOVA_SEO_KEY" -H "Content-Type: application/json" -d '{}'

# A health check of one site (use a site_id from list_sites)
curl -s https://runnova.ai/api/seo/v1/audit_site \
  -H "Authorization: Bearer $NOVA_SEO_KEY" -H "Content-Type: application/json" \
  -d '{"site_id": "ada7ac3856d84300b8c1fd6ce53b95a7"}'
json (audit_site answer)
{
  "score": 99,
  "pages": 1,
  "issues": [
    {
      "code": "img_alt",
      "severity": "info",
      "page": "/",
      "message": "2 image(s) have no description (alt text).",
      "fix": "Describe each image in a few words in its alt attribute."
    }
  ]
}

Python

python
import os, requests

KEY = os.environ["NOVA_SEO_KEY"]

def nova_seo(tool, **args):
    r = requests.post(f"https://runnova.ai/api/seo/v1/{tool}",
                      headers={"Authorization": f"Bearer {KEY}"}, json=args, timeout=120)
    if r.status_code == 400:
        raise ValueError(r.json()["error"])   # a plain-words reason you can act on
    r.raise_for_status()
    return r.json()

for site in nova_seo("list_sites")["sites"]:
    check = nova_seo("audit_site", site_id=site["site_id"])
    print(site["url"], check["score"], len(check["issues"]), "issues")

JavaScript

javascript
async function novaSeo(tool, args = {}) {
  const res = await fetch(`https://runnova.ai/api/seo/v1/${tool}`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.NOVA_SEO_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(args),
  });
  const data = await res.json();
  if (!res.ok) throw new Error(data.error || data.detail || res.statusText);
  return data;
}

const { sites } = await novaSeo("list_sites");

Answers and errors

200Done. The JSON is the tool's answer.
400Something to fix on your side, explained in {"error": "..."}, for example "Prove you own this site first" or "No site with that id on this account".
401No key, a wrong key, or a revoked key.
404There is no tool with that name.
429Too many calls in a minute. Wait for the number of seconds in the Retry-After header and try again.

Over MCP, a problem with a tool call comes back as a normal answer marked isError with the same plain-words message, so the AI app can read it and tell you what to do.

Background work

study_site and check_ai_visibility start work and answer at once with "started": true. Call get_report a minute or two later (a few minutes for visibility) to read the results. Starting a study while one is running does not start a second one.

Join our Discord

Chat with our engineers and become part of the active NOVA developer community.

Join Discord

Need help?

Open an issue on GitHub or email support@bridgeye.com.

Get help
Bridgeye • Autonomous Software Engineering.