NOVA SEO API
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
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"}'{
"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
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
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.
Need help?
Open an issue on GitHub or email support@bridgeye.com.